Syntaxe de documentation de la structure JSON

Question

Donc, je suis en train de document au format json renvoyé par une api, je suis en train d'écrire contre et je voudrais savoir si il y a n'importe quel format populaire pour la documentation de la structure json.

Remarque je ne suis pas en train de tester ou valider quoi que ce soit, je suis juste à l'aide de cette documentation. Aussi certaines façons d'ajouter des commentaires à des non-constantes(articles toujours retourné w/ de la même valeur), ce serait bien.

Ce la n'est pas totalement 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 Schema pourrait servir à cette fin, mais dans la pratique, je ne suis pas sûr qu'il fait. La peine de mentionner, je l'espère.

Autre que cela, mon opinion personnelle est que, depuis le JSON est principalement utilisé pour le transfert des objets, la documentation équivalente des objets dans la langue du client utilise (Java, C#, différents langages de script) peut faire plus de sens -- après tout, de tels objets sont généralement mappé liée à JSON et à l'arrière. Et puis vous pouvez utiliser n'importe quel outils de documentation sont disponibles, comme Javadoc pour Java (perldoc pour Perl, de l'Oxygène pour le c++, etc etc).

Pour la spécification des interfaces, il est également WADL (Web App Description Language), ce qui pourrait aider.

Answer 2

Comment générer la Documentation HTML à partir de JSON:

Vous aurez besoin de générer un Schéma Json, il est ce service que vous pouvez coller à l'origine du JSON et de générer automatiquement le Schéma:

http://www.jsonschema.net/

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

https://github.com/mattyod/matic

La génération de code HTML

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

Sur Windows, exécuter CMD

Installer Jade de l'exécution de cette commande: npm install -g jade

Ouvrez le fichier Téléchargé Matic dossier à partir de Github: cd PATH_TO_FOLDER/matic

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

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

Mettez votre schéma dans le dossier des "schémas"

Ouvrez le dossier de projet: cd PATH_TO_PROJECT_FOLDER

Commande exécuter: matic

Vous devriez voir un message de succès: Documentation built to ./web/

Answer 3

Je ne suis pas sûr pourquoi vous essayez de document JSON, je peux deviner 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) peut-être ce que vous cherchez.

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
}

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

Un exemple rapide:

Author:
  name: String
  clicked: Boolean
  created: Integer

Answer 4

Pour les Api simple où chaque JSON morceau n'est qu'un ou deux niveaux de profondeur, puis de documenter en montrant des exemples qui semble être la pratique courante.

Cependant, pour plus des modèles de données complexes telles que la vôtre, je n'ai pas une bonne solution. Il y a quelques JSON schéma les propositions, mais qui semble aller à l'encontre de l'esprit de JSON, et semble trop lourd pour que votre but est juste de la documentation.

Personnellement, je pense que votre système est très bonne. Avec quelques petites extensions pour gérer facultatif et alternative sections, je pense qu'il pourrait être tout aussi expressifs que Backus-Naur Form, très facile à lire et à comprendre, et être en accord avec l'esprit de JSON. Nous pouvons peut-être obtenir un certain élan derrière les autres à utiliser ce "Taycher JSON de Grammaire de Forme" (TJGF)!

Answer 5

Vous pouvez écrire un exemple de réponse JSON puis le documenter à l'aide de Markdown et de Docco . Docco produit une documentation facile à suivre basée sur HTML.