Пасека: возможно ли документировать, какие поля ответа JSON?
-
21-12-2019 - |
Вопрос
Я хотел бы документировать, что представляют собой фактические сами поля JSON.
Я документировал операторы Get, а параметры, но это не делает полную документацию, чтобы дать пользователям.
Так, в примере ниже, как бы я добавил комментарий о «других полях».Это поддерживается?Или мне нужно сделать компаньонный документ где-то еще.
## View Applications [/cat{?sort}{&order}{&page}]
### List all Applications
### Get List of Applications [GET]
+ Parameters
+ sort (optional, string) ... `sort` parameter is used to specify which criteria to use for sorting. One of the following strings may be used:
`"NAME",
"RATING", "QUALITY" ,
"RISKLEVEL", `
+ order (optional, string) ... `order` parameter is used to specify which order to use if sorting is used. One of the following strings may be used:
`"ASC",
"DESC"`
+ page (optional, int ) ... `page` parameter is used to request subsequent catalog pages.
+ Response 200 (application/json)
{
"Catalog" : {
"Page" : 0,
"Count" : 6,
"Applications" : [{
"UID" : "6882e96a-5da1-11e3-1111-3f24f45df3ad"
"OtherFields: ""
}]
}}
. Решение
Обновление: Мы только что развернули бета-версию описания атрибутов, используя mson Syntax .
Оригинальная полезная нагрузка может затем описана как
### Get List of Applications [GET]
+ Response 200 (application/json)
+ Attributes
+ Catalog (object)
+ Page: 0 (number) - Number of the page
+ Count: 6 (number) - Count of *Lorem Ipsum*
+ Applications (array) - Some array of something
+ (object)
+ UID: `6882e96a-5da1-11e3-1111-3f24f45df3ad`
+ OtherFields
+ Body
{
"Catalog" : {
"Page" : 0,
"Count" : 6,
"Applications" : [{
"UID" : "6882e96a-5da1-11e3-1111-3f24f45df3ad"
"OtherFields": ""
}]
}
}
.
Примечание. Явный JSON в теле является избыточным, и вы можете пропустить его полностью.См. Спецификация чертежа API - / a> Для дополнительных деталей
Другие советы
Я не думаю, что он еще поддерживается.
Я решил эту проблему в моем проекте, поместив таблицу с описанием прямо над строкой запроса Get.В вашем случае это может выглядеть:
### List all Applications
| Field | Description |
|----------------------------------|---------------------------|
| Catalog.Applications.OtherFields | Documentation goes here.. |
### Get List of Applications [GET]
.
Чтобы помочь вам создать таблицу в синтаксисе Markdown, вы можете использовать Генератор таблиц разметки .
Обратите внимание, что генератор таблицы позволяет сохранить определение таблицы в файл, чтобы в следующий раз вам нужно редактировать таблицу, с которой вы можете начать с того места, где вы остановились.