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

Итак, я пытаюсь задокументировать формат 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
}

Ответ 1

В теории JSON Schema может служить этой цели, но на практике я не уверен, что это так. Надеюсь упомянуть.

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

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

Ответ 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

Откройте папку Downloaded 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/

Ответ 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

Ответ 4

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

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

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

Ответ 5

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

Ответ 6

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

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

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

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