Тело запроса и ответа на запрос смешивания

Question

Я хотел бы использовать проект aglio/api для создания хорошей документации для нашего нового API.

JSON может быть довольно большим (с большим количеством дополнительных значений), поэтому я хотел бы дать правильный пример использования в теле, но также использовать структуры данных для схемы json. Однако, всякий раз, когда схема подходит точно к телу, полученный HTML-код бросает мне «Hello, world!», Так как я не заполнял данные примера, но поскольку у меня есть полный и действительный пример в теле , Я бы не ожидал, что aglio создаст выход Hello World.

Для справки, это то, что я хотел бы ожидать в результате HTMLs тела появляются:

{ 
    "a": "i want this to appear", 
    "b": "in my aglio", 
    "c": "html file" 
} 

Это то, что на самом деле делает появляться:

{ 
    "a": "Hello, world!", 
    "b": "Hello, world!", 
    "c": "Hello, world!", 
    "d": "Hello, world!" 
} 

И это сырье апи план:

FORMAT: 1A 

# JSON Schema 

# Test [/post/something] 

## A Test [POST] 

+ Request (application/json) 
    + Attributes (SomeObject) 

    + Body 

     { 
      "a": "i want this to appear", 
      "b": "in my aglio", 
      "c": "html file" 
     } 

+ Response 200 

# Data Structures 
## SomeObject (object) 
+ a (string) - A 
+ b (string) - B 
+ c (string) - C 
+ d (string, optional) - I'm optional, yet don't want to appear in the html, only the schema 

Итак, во-первых: это правильный способ сделать что-то? Вы порекомендовали бы другой подход? Это ошибка в aglio, потому что на пасеке она работает так, как я ее намерен? Спасибо!

Answer 1

Обнаружена соответствующая проблема github, похоже, что ничего не случилось с моим описанием. https://github.com/danielgtaylor/aglio/issues/221

Answer 2

Вы можете сделать следующее

FORMAT: 1A 
# JSON Schema 
# Test [/post/something] 
JSON Schema Title 
## A Test [POST] 

+ Request (application/json) 
    + Attributes (object) 
     + a a-value (string, required) - description about a 
     + b b-value (number, required) - description about b 
     + c c-value (string, required) - description about c 
     + d [a1, a2, a3] (array, optional) - I'm optional 

+ Response 200 (application/json) 
    { 
    "message": "this works" 
    } 

а-значение (строка обязательно) - описание В строке выше "а" -> имя атрибута, "а-значение" -> появляется в теле, «(строка, обязательно)» -> для генерации схемы, «описание» -> описание атрибута схемы