web-dev-qa-db-fra.com

Syntaxe de documentation de la structure JSON

J'essaie donc de documenter le format du json retourné par une API contre laquelle j'écris et je voudrais savoir s'il existe un format populaire pour la documentation de la structure json.

Remarque Je n'essaie pas de tester ou de valider quoi que ce soit, je l'utilise simplement pour la documentation. De plus, certaines façons d'ajouter des commentaires à des non-constantes (les éléments retournent toujours avec la même valeur) seraient bien.

C'est le schéma pas totalement pensé que j'utilise actuellement:

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
}
jsondocumentationnotation
66
Roman A. Taycher

En théorie Schéma JSON pourrait servir cet objectif, mais en pratique, je ne suis pas sûr que ce soit le cas. Il convient de mentionner que j'espère.

En dehors de cela, mon opinion personnelle est que, puisque JSON est principalement utilisé pour le transfert d'objets, la documentation d'objets équivalents dans les utilisations du client de langage (Java, C #, divers langages de script) peut être plus logique - après tout, ces objets sont généralement mappés/liés à JSON et retour. Et puis vous pouvez utiliser tous les outils de documentation disponibles, comme Javadoc pour Java (perldoc pour Perl, Oxygen pour c ++ etc etc)).

Pour spécifier les interfaces, il existe également WADL (Web App Description Language), ce qui pourrait être utile.

32
StaxMan

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

Vous devrez générer un schéma Json , il y a ce service que vous pouvez coller le JSON d'origine et générer automatiquement le schéma:

http://www.jsonschema.net/

Avec le schéma en main, vous pouvez générer automatiquement la documentation HTML à l'aide de Matic.

https://github.com/mattyod/matic

Génération de HTML

Pour installer Matic, vous devrez installer Node.js: http://nodejs.org/

Sous Windows, exécutez CMD

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

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

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

Téléchargez un exemple de projet de documentation: 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: matic

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

14
Carlos Oliveira

Je ne sais pas pourquoi vous essayez de documenter JSON, je suppose que vous essayez de trouver un moyen cohérent de 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 recherchez.

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
}

Alternativement 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 peut être mieux adapté pour documenter votre structure de données.

Un exemple rapide:

Author:
  name: String
  clicked: Boolean
  created: Integer
7
SnatchFrigate

Pour les API simples où chaque bloc JSON n'a qu'un ou deux niveaux de profondeur, la documentation en montrant des exemples semble être la pratique courante.

Cependant, pour des modèles de données plus complexes tels que le vôtre, je n'ai pas trouvé de bonne solution. Il existe quelques propositions de schéma JSON, mais cela semble aller à l'encontre de l'esprit de JSON, et semble trop lourd pour votre simple objectif de documentation.

Personnellement, je pense que votre plan est très bon. Avec quelques petites extensions pour gérer les sections optionnelles et alternatives, je pense que cela pourrait être aussi expressif que Backus-Naur Form, être très facile à lire et à comprendre, et être en accord avec l'esprit de JSON. Peut-être que nous pouvons obtenir un certain élan derrière les autres pour utiliser ce "Taycher JSON Grammar Form" (TJGF)!

5
Eamonn O'Brien-Strain

Vous pouvez écrire un exemple de réponse JSON puis la documenter en utilisant Markdown et Docco . Docco génère une documentation HTML facile à suivre.

3
Josh Schumacher

Cela peut ne pas être utile dans votre cas car il semble que vous ne construisiez pas d'API.

Mais si c'était le cas et que vous utilisiez Java ou JVM (JAX-RS), vous auriez pu utiliser Swagger.

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

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

3
Sebastien Lorber