Sintaxis para documentar la estructura JSON

Question

Así que estoy tratando de documentar el formato de la json devuelta por una API contra la que estoy escribiendo y quisiera saber si hay algún formato popular para la documentación de la estructura json.

Nota 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.

Esta el no totalmente pensada esquema Actualmente estoy usando:

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 
} 

Answer 1

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

Aparte de esto, mi opinión personal es que, dado que JSON se utiliza principalmente 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, tales objetos usualmente están mapeados/enlazados a JSON y viceversa. Y luego puede usar cualquier herramienta de documentación disponible, como Javadoc para Java (perldoc para Perl, Oxygen para C++, etc.).

Para especificar las interfaces también existe WADL (Lenguaje de descripción de la aplicación web), lo que podría ayudar.

Answer 2

No estoy seguro de por qué está tratando de documentar JSON, puedo adivinar que trata de encontrar una manera consistente de decirle a un IDE o un desarrollador los tipos de datos en su 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 su tratando de demostrar la estructura de los 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 

Answer 3

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

Answer 4

Para API simples donde cada fragmento JSON tiene solo uno o dos niveles de profundidad, entonces documentar mostrando ejemplos parece ser la práctica común.

Sin embargo, para modelos de datos más complejos como el suyo, 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 su 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)!

Answer 5

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

Usted tendrá que generar un Json Schema, no existe este servicio que se puede pegar el JSON original y concesionarios generar el esquema:

http://www.jsonschema.net/

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

https://github.com/mattyod/matic

Generación de HTML

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

En Windows, ejecute CMD

Instalar Jade ejecutar este comando: npm install -g jade

Abra la carpeta Downloaded Matic de Github: cd PATH_TO_FOLDER/matic

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

Descargar un proyecto ejemplo documentación: https://github.com/mattyod/matic-simple-example

Deja tus esquema en los "esquemas" de carpetas

Abra la carpeta del proyecto: cd PATH_TO_PROJECT_FOLDER

comando Ejecutar: matic

debería ver un mensaje de éxito: Documentation built to ./web/

Answer 6

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

Pero si fuera el caso y estuviera usando Java o JVM (JAX-RS), podría 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/