Синтаксис для документирования структуры JSON

Question

Итак, я пытаюсь задокументировать формат json, возвращаемого API, против которого я пишу, и я хотел бы знать, есть ли какой-нибудь популярный формат для документации структуры json.

Примечание. Я не пытаюсь что-либо тестировать или проверять, я просто использую это для документации.Также было бы неплохо добавить несколько комментариев к неконстантам (элементы всегда возвращались с одним и тем же значением).

Это не совсем продуманная схема, которую я сейчас использую:

Plain names refer to identifiers or types.
Some types have type-comment
Strings that appear to be constant(always returned for that type of request) strings are "str"
Constant Numbers would be just the number
Constant null is null
Booleans are true/false for constant booleans or Boolean otherwise
[a,b,c] are lists with 3 items a,b,c
[...  ...] is a list of repeating elements of some types/constants/patterns
{a:A,b:B,c:c} and {... ...}  is the same for a dictionary.

пример:

story          := [header,footer]
header         := {"data":realHeader,"kind":"Listing"}
realHeader     := {"after": null, "before": null, "children": [{"data": realRealHeader, "kind": "t3"}], "modhash": ""}
footer         := {"data":AlmostComments,"kind":"Listing"}
AlmostComments := {"data": {"after": null, "before": null, "children": comments, "modhash": ""}, "kind": "t1"}
comments       := [...{"data":comment, "kind":"t1"}...]

realRealHeader :=
{"author": string,
"clicked": boolean,
"created": int,
"created_utc": int,
"domain": "code.reddit.com",
"downs": int,
"hidden": boolean,
"id": string-id,
"is_self": boolean,
"levenshtein": null,
"likes": null,
"media": null,
"media_embed": { },
"name": string-id,
"num_comments": int,
"over_18": false,
"permalink": string-urlLinkToStoryStartingFrom/r,
"saved": false,
"score": int,
"selftext": string,
"selftext_html": string-html,
"subreddit": string-subredditname,
"subreddit_id": string-id,
"thumbnail": "",
"title": string,
"ups": int,
"url": "http://code.reddit.com/"
}


comments := {
"author": string,
"body": string-body_html-wout-html,
"body_html": string-html-formated,
"created": int,
"created_utc": int,
"downs": int,
"id": string-id,
"levenshtein": null,
"likes": null,
"link_id": string-id,
"name": string-id",
"parent_id": string-id,
"replies": AlmostComments or null,
"subreddit": string-subredditname,
"subreddit_id": string-id,
"ups": int
}

Answer 1

Теоретически Схема JSON могла бы служить этой цели, но на практике я не уверен, что это так. Надеюсь, стоит упомянуть.

Кроме этого, мое личное мнение заключается в том, что, поскольку JSON преимущественно используется для передачи объектов, документирование эквивалентных объектов на языке, используемом клиентом (Java, C #, различные языки сценариев), может иметь больше смысла - ведь такие объекты обычно сопоставлены / привязаны к JSON и обратно. И затем вы можете использовать любые доступные инструменты документирования, такие как Javadoc для Java (perldoc для Perl, Oxygen для c ++ и т. Д. И т. Д.).

Для указания интерфейсов также может быть WADL (язык описания веб-приложений), который может помочь.

Answer 2

Как сгенерировать HTML-документацию из JSON:

Вам потребуется сгенерировать Json Schema , есть этот сервис, в который вы можете вставить оригинальный JSONи автоматически сгенерировать схему:

http://www.jsonschema.net/

Имея схему в руках, вы можете автоматически сгенерировать документацию HTML с помощью Matic.

https://github.com/mattyod/matic

Генерация HTML

Для установки Matic вам потребуется установить Node.js: http://nodejs.org/

В Windows запустите CMD

Установите Jade, запустив этукоманда: npm install -g jade

Откройте папку «Загруженный Matic» с Github: cd PATH_TO_FOLDER/matic

Запустите команду установки: npm install -g

Загрузите документацию с примером проекта: https://github.com/mattyod/matic-simple-example

Поместите вашу схему в папку "схемы"

Откройте папку проекта: cd PATH_TO_PROJECT_FOLDER

Запустите команду: matic

Вы должныувидеть сообщение об успехе: Documentation built to ./web/

Answer 3

Я не уверен, почему вы пытаетесь задокументировать JSON, я могу догадаться, что вы пытаетесь найти последовательный способ сообщить IDE или разработчику типы данных в вашей записи.

jsdoc (http://jsdoc.sourceforge.net/#usage) может быть тем, что вы ищете.

например:

{
   /**
     * Name of author
     * @type String
     */
   "author": null, 
   /**
     * has the author been clicked
     * @type Boolean
     */
   "clicked": null, 
   /**
     * Unix Timestamp of the creation date
     * @type Int
     */
   "created": null
}

В качестве альтернативы, если вы пытаетесь продемонстрировать структуру ваших данных. Вы можете посмотреть на YAML (http://www.yaml.org/), эторазработан, чтобы быть читаемым человеком форматом сериализации, который, возможно, лучше подходит для документирования вашей структуры данных.

Быстрый пример:

Author:
  name: String
  clicked: Boolean
  created: Integer

Answer 4

Для простых API, где каждый блок JSON имеет глубину только один или два уровня, тогда документирование с помощью примеров кажется обычной практикой.

Однако для более сложных моделей данных, таких как ваша, я не виделлюбое хорошее решение.Существует несколько предложений по схемам JSON, но это, кажется, идет вразрез с духом JSON и кажется слишком тяжелым для вашей цели просто документирования.

Лично я считаю, что ваша схема очень хорошая.Имея несколько небольших расширений для обработки необязательных и альтернативных разделов, я думаю, что он может быть таким же выразительным, как и форма Бэкуса-Наура, быть очень простым для чтения и понимания и соответствовать духу JSON.Возможно, мы сможем получить импульс от других, чтобы использовать эту «форму грамматики JSON Taycher» (TJGF)!

Answer 5

Это может быть бесполезно в вашем случае, так как кажется, что вы не создаете API.

Но если бы это было так и вы использовали Java или JVM (JAX-RS), вы могли бы использовать Swagger.

Позволяет описывать ваш API в представлении JSON (например, WSDL / WADL). И они предоставляют уровень IHM, который читает это представление JSON вашего API. Вот что вы получите: http://petstore.swagger.wordnik.com/

https://developers.helloreverb.com/swagger/

Answer 6

Вы можете написать пример ответа JSON, а затем задокументировать его, используя Markdown и Docco . Docco легко выводит документацию на основе HTML.