Синтаксис для документирования структуры 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
}
6 ответов:
в теории JSON Schema может служить этой цели, но на практике я не уверен, что он делает. Стоит упомянуть, я надеюсь.
кроме этого, мое личное мнение заключается в том, что, поскольку JSON преимущественно используется для передачи объектов, документирование эквивалентных объектов в использовании языка клиента (Java, C#, различные языки сценариев) может иметь наибольший смысл-в конце концов, такие объекты обычно сопоставляются/привязываются к JSON и обратно. И тогда вы можете использовать любые инструменты документации доступно, например Javadoc для Java (perldoc для Perl, Oxygen для c++ и т. д.).
для указания интерфейсов есть тоже WADL (язык описания веб-приложения), что может помочь.
как создать HTML-документацию из JSON:
вам нужно будет создать В JSON-Схемы, есть этот сервис, который вы можете вставить оригинальный JSON и автоматически генерировать схему:
со схемой в руках вы можете автоматически генерировать документацию HTML с помощью Матич.
https://github.com/mattyod/matic
генерация HTML
для установки Matic вам понадобится установить узел.js: http://nodejs.org/
в Windows запустите CMD
установите Jade, выполнив эту команду:
npm install -g jadeоткройте загруженную папку Matic из Github:
cd PATH_TO_FOLDER/maticвыполните команду install:
npm install -gСкачать пример документации проект: https://github.com/mattyod/matic-simple-example
поместите свою схему в папку "схемы"
открыть папку проекта:
cd PATH_TO_PROJECT_FOLDERвыполнить команду :
maticвы должны увидеть сообщение об успешном выполнении :
Documentation built to ./web/
Я не уверен, почему вы пытаетесь документировать 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
для простых API, где каждый фрагмент JSON имеет только один или два уровня глубины, то документирование, показывая примеры, кажется, является обычной практикой.
однако для более сложных моделей данных, таких как Ваша, я не видел ни одного хорошего решения. Есть некоторые предложения схемы JSON, но это, похоже, противоречит духу JSON и кажется слишком тяжелым для вашей цели просто документирования.
лично я считаю, что ваша схема очень хороша. С несколькими небольшими расширениями чтобы справиться с дополнительными и альтернативными разделами, я думаю, что это может быть так же выразительно, как форма Backus-Naur, очень легко читать и понимать и соответствовать духу JSON. Возможно, мы можем получить некоторый импульс позади других, чтобы использовать эту "грамматическую форму Taycher JSON" (TJGF)!
вы можете написать пример ответа JSON, а затем документировать его с помощью Markdown и Docco. Docco выводит легко следовать документации на основе HTML.
Это может быть не полезно в вашем случае, так как кажется, что вы не строите API.
но если бы это было так, и вы использовали Java или JVM (JAX-RS), вы могли бы использовать Swagger.
Это позволяет описывать ваш API в представлении JSON (например, WSDL/WADL). И они предоставляют слой IHM, который читает это представление JSON вашего API. Вот что вы получите: http://petstore.swagger.wordnik.com/
Comments