Синтаксис для документирования структуры 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
}
61
documentation json notation

6 ответов

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

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

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

28

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

вам нужно будет создать Схема Json, есть эта служба, которую вы можете вставить исходный JSON и автоматически генерировать схему:

http://www.jsonschema.net/

со схемой в руках вы можете автоматически генерировать документацию HTML, используя Матич.

https://github.com/mattyod/matic

создание HTML

для установки Matic вам понадобится установить узел.Яш: http://nodejs.org/

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

Install Jade запуск этой команды: npm install -g jade

откройте загруженную папку Matic из Github: cd PATH_TO_FOLDER/matic

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

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

поместите свою схему в папку "schemas"

открыть папку проекта: cd PATH_TO_PROJECT_FOLDER

выполнить команду : matic

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

11

Я не уверен, почему вы пытаетесь документировать 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
7

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

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

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

4

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

3

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

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

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

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

3