formato - json validator

Sintaxis para documentar la estructura JSON (6)

En teoría, JSON Schema podría servir para este propósito, pero en la práctica no estoy seguro de que lo haga. Vale la pena mencionarlo, espero.

Aparte de esto, mi opinión personal es que, dado que JSON se utiliza predominantemente para transferir objetos, documentar objetos equivalentes en los usos del cliente de lenguaje (Java, C #, varios lenguajes de scripting) puede tener más sentido; después de todo, dichos objetos suelen asignarse / encuadernarse a JSON y de vuelta. Y luego puede usar cualquier herramienta de documentación disponible, como Javadoc para Java (perldoc para Perl, Oxygen para c ++, etc.).

Para especificar interfaces, también está WADL (Lenguaje de descripción de la aplicación web), que podría ser útil.

Así que estoy tratando de documentar el formato del json devuelto por una API que escribo en contra y me gustaría saber si hay algún formato popular para la documentación de la estructura json.

Tenga en cuenta que no estoy tratando de probar o validar nada, solo estoy usando esto para la documentación. También algunas formas de agregar comentarios a no constantes (elementos siempre devueltos con el mismo valor) serían agradables.

Este es el esquema no totalmente pensado que estoy usando actualmente:

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.

ejemplo:

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 }

No estoy seguro de por qué estás tratando de documentar JSON, puedo adivinar que tratas de encontrar una forma consistente de decirle a un IDE o un desarrollador los tipos de datos en tu notación.

jsdoc (http://jsdoc.sourceforge.net/#usage) podría ser lo que estás buscando.

por ejemplo:

{ /** * 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 }

Alternativamente, si intenta demostrar la estructura de sus datos. Puede consultar YAML (http://www.yaml.org/), está diseñado para ser un formato de serialización legible para los humanos que quizás sea más adecuado para documentar su estructura de datos.

Un ejemplo rápido:

Author: name: String clicked: Boolean created: Integer

Para las API simples donde cada fragmento JSON tiene solo uno o dos niveles de profundidad, la documentación que muestra ejemplos parece ser la práctica común.

Sin embargo, para modelos de datos más complejos como el tuyo, no he visto ninguna buena solución. Hay algunas propuestas de esquema JSON, pero eso parece ir en contra del espíritu de JSON, y parece demasiado pesado para su propósito de solo documentar.

Personalmente, creo que tu esquema es muy bueno. Con algunas pequeñas extensiones para manejar secciones opcionales y alternativas, creo que podría ser tan expresivo como Backus-Naur Form, ser muy fácil de leer y comprender, y estar en consonancia con el espíritu de JSON. ¡Tal vez podamos obtener algo de impulso detrás de otros para usar este "Formulario de gramática de JSON de Taycher" (TJGF)!

Podría escribir una respuesta JSON de muestra y luego documentarla usando Markdown y Docco . Docco genera fácilmente documentación basada en HTML fácil de seguir.

Puede que no sea útil en su caso, ya que parece que no está creando una API.

Pero si fuera el caso y estuvieras usando Java o JVM (JAX-RS), podrías haber usado Swagger.

Permite describir su API en una representación JSON (como WSDL / WADL). Y proporcionan una capa IHM que lee esa representación JSON de su API. Esto es lo que obtendrá: http://petstore.swagger.wordnik.com/

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

Cómo generar una documentación HTML de JSON:

Necesitará generar un Esquema Json , existe este servicio que puede pegar el JSON original y generar automáticamente el Esquema:

http://www.jsonschema.net/

Con el esquema en las manos, puede generar automáticamente la documentación HTML usando Matic.

https://github.com/mattyod/matic

Generando HTML

Para instalar Matic, necesitará instalar Node.js: http://nodejs.org/

En Windows, ejecute CMD

Instale Jade ejecutando este comando: npm install -g jade

Abra la carpeta Matic descargada desde Github: cd PATH_TO_FOLDER/matic

Ejecute el comando de instalación: npm install -g