Смешать тело запроса / ответа и структуры данных

Question

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

JSON может быть довольно большим (с большим количеством необязательных значений), поэтому я хотел бы дать правильный вариант использования в теле, но также использовать структуры данных для схемы json. Однако всякий раз, когда схема соответствует точно телу, результирующий HTML-код выдает мне "Hello, world!", Так как я не заполнил данные примера - но так как у меня есть полный и правильный пример в теле, Я бы не ожидал, что allio создаст выход 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!"
}

И это сырой план API:

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

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

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"
    }

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

Answer 2

Нашел соответствующую проблему github, похоже, с моим описанием все в порядке. https://github.com/danielgtaylor/aglio/issues/221