Syntaxe pour documenter la structure JSON

Question

Je suis en train de documenter le format du JSON retourné par un api Je suis en train d'écrire contre et je voudrais savoir s'il y a un format populaire pour la documentation de la structure JSON.

Note Je ne cherche pas à tester ou quoi que ce soit validate, je suis juste en utilisant cette documentation. En outre, certaines façons d'ajouter des commentaires aux non-constantes (éléments toujours retournés w / la même valeur) serait bien.

pas tout à fait le schéma pensé que je suis actuellement en utilisant:

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.

exemple:

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 théorie JSON schéma pourrait servir à cette fin, mais dans la pratique, je ne suis pas sûr qu'il fait. Il convient de mentionner que je l'espère.

Autre que cela, mon opinion personnelle est que depuis JSON est principalement utilisé pour transférer des objets, la documentation des objets équivalents dans les utilisations des clients de langue (Java, C #, divers langages de script) peuvent faire plus de sens - après tout, ces objets sont généralement cartographié / lié à JSON et à l'arrière. Et vous pouvez utiliser tous les outils de documentation sont disponibles, comme Javadoc pour Java (perldoc pour Perl, oxygène pour c ++ etc etc).

Pour les interfaces spécifiant il y a aussi WADL (Web App Description Language), ce qui peut aider.

Answer 2

Comment générer une documentation HTML à partir JSON:

Vous devez générer une Json schéma , il y a ce service que vous pouvez coller l'JSON et orginal générer automatiquement le schéma:

http://www.jsonschema.net/

Avec le schéma dans les mains, vous pouvez générer automatiquement la documentation HTML en utilisant Matic.

https://github.com/mattyod/matic

Génération HTML

Pour installer Matic, vous aurez besoin d'installer Node.js: http://nodejs.org/

Sous Windows, exécutez CMD

Installer Jade exécutant cette commande: npm install -g jade

Ouvrez le dossier téléchargé Matic de Github: cd PATH_TO_FOLDER/matic

Exécuter la commande d'installation: npm install -g

Télécharger un exemple de la documentation du projet: https://github.com/mattyod/matic-simple-example

Mettez votre schéma dans le dossier « schémas »

Ouvrez le dossier du projet: cd PATH_TO_PROJECT_FOLDER

Exécuter la commande suivante: matic

Vous devriez voir un message de réussite: Documentation built to ./web/

Answer 3

Je ne suis pas sûr de savoir pourquoi vous essayez de documenter JSON, je devine que vous essayez de trouver une manière cohérente pour dire un IDE ou un développeur les types de données sur votre notation.

jsdoc (http://jsdoc.sourceforge.net/#usage) pourrait être ce que vous êtes à la recherche.

par exemple:

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

Par ailleurs, si vous essayez de démontrer la structure de vos données. Vous pouvez regarder YAML (http://www.yaml.org/), il est conçu pour être un format de sérialisation lisible par l'homme qui mieux adapté peut-être pour documenter votre structure de données.

Un exemple rapide:

Author:
  name: String
  clicked: Boolean
  created: Integer

Answer 4

Pour les API simples où chaque morceau JSON est seulement un ou deux niveaux de profondeur, documentant puis en montrant des exemples semble être la pratique courante.

Cependant, pour les modèles de données plus complexes comme le vôtre, je n'ai pas vu une bonne solution. Il y a des propositions de schéma JSON, mais qui semble aller à l'encontre de l'esprit de JSON, et semble trop lourd pour votre objectif de simplement documenter.

Personnellement, je pense que votre système est très bon. Avec quelques petites extensions pour gérer des sections facultatives et d'autres, je pense que ce pourrait être tout aussi expressif que Backus-Naur, être très facile à lire et à comprendre, et être conforme à l'esprit de JSON. Peut-être que nous pouvons obtenir un certain élan derrière les autres à utiliser cette « grammaire Taycher JSON Form » (TJGF)!

Answer 5

Vous pouvez écrire une réponse JSON de l'échantillon et Documentez ensuite à l'aide Markdown et Docco . de Docco facile à suivre la documentation basée sur HTML.

Answer 6

Il ne peut pas être utile dans votre cas, car il semble que vous n'êtes pas la construction d'une API.

Mais si ce fut le cas et que vous utilisiez Java ou JVM (JAX-RS), vous auriez pu utiliser Swagger.

Il permet de décrit votre API dans une représentation JSON (comme WSDL / WADL). Ils fournissent une couche qui lit cette IHM représentation JSON de votre API. Voici ce que vous obtiendrez: http://petstore.swagger.wordnik.com/

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