Syntax für die Dokumentation der JSON-Struktur

Question

Also ich versuche, das Format der JSON von einer API zurückgegeben, ich schreibe gegen und ich würde gerne wissen, ob es ein beliebiges Format für die Dokumentation der JSON-Struktur gibt.

Hinweis Ich versuche nicht, etwas zu testen oder zu validieren, ich benutze es nur zur Dokumentation. Es gibt auch einige Möglichkeiten, Kommentare zu Nicht-Konstanten hinzuzufügen (Elemente, die immer mit demselben Wert zurückgegeben werden).

Dies ist die nicht ganz durchdacht Schema ich zur Zeit mit:

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. 

Beispiel:

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

Theoretisch JSON Schema diesen Zweck dienen könnte, aber in der Praxis bin ich nicht sicher, ob es funktioniert . Erwähnenswert, hoffe ich.

Meine persönliche Meinung ist, dass, da JSON hauptsächlich für die Übertragung von Objekten verwendet wird, die Dokumentation äquivalenter Objekte in Sprache Client-Anwendungen (Java, C#, verschiedene Skriptsprachen) am sinnvollsten sein - schließlich solche Objekte in der Regel werden an JSON und zurück gemappt/gebunden. Und dann können Sie alle verfügbaren Dokumentationstools verwenden, wie Javadoc für Java (perldoc für Perl, Oxygen für C++ usw.).

Für die Angabe von Schnittstellen gibt es auch WADL (Web App Description Language), die helfen könnte.

Answer 2

Ich bin mir nicht sicher, warum Sie versuchen, JSON zu dokumentieren, ich kann Ihren Versuch erraten, einen konsistenten Weg zu finden, um einer IDE oder einem Entwickler die Datentypen auf Ihrer Notation mitzuteilen.

jsdoc (http://jsdoc.sourceforge.net/#usage) könnte das sein, was Sie suchen.

zum Beispiel:

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

Alternativ, wenn Ihr versucht, die Struktur Ihrer Daten zu demonstrieren. Sie könnten sich YAML (http://www.yaml.org/) ansehen, es wurde entwickelt, um ein von Menschen lesbares Format für die Serialisierung zu sein, das vielleicht besser dafür geeignet ist, Ihre Datenstruktur zu dokumentieren.

Ein kurzes Beispiel:

Author: 
    name: String 
    clicked: Boolean 
    created: Integer 

Answer 3

Sie könnten eine Probe JSON Antwort schreiben und dann dokumentieren Abschlag und Docco verwenden. Docco gibt einfach HTML-basierte Dokumentation aus.

Answer 4

Für einfache APIs, bei denen jeder JSON-Chunk nur ein oder zwei Ebenen tief ist, scheint die Dokumentation anhand von Beispielen die gängige Praxis zu sein.

Allerdings habe ich für komplexere Datenmodelle wie Ihres keine gute Lösung gesehen. Es gibt einige JSON-Schema-Vorschläge, aber das scheint gegen den Geist von JSON zu gehen und scheint zu schwer für den Zweck der Dokumentation zu sein.

Persönlich denke ich, Ihr Schema ist sehr gut. Mit ein paar kleinen Erweiterungen für optionale und alternative Abschnitte könnte ich sagen, dass sie genauso ausdrucksstark sein können wie Backus-Naur Form, sehr leicht zu lesen und zu verstehen sein und dem Geist von JSON entsprechen. Vielleicht können wir etwas Schwung hinter anderen bringen, um dieses "Taycher JSON Grammar Form" (TJGF) zu verwenden!

Answer 5

Wie man eine HTML-Dokumentation von JSON generieren:

Sie benötigen einen Json Schema zu erzeugen, gibt es diesen Service, der Ihnen die ursprünglichen JSON einfügen können und Auto erzeugen das Schema:

http://www.jsonschema.net/

Mit dem Schema in Händen können Sie automatisch die HTML-Dokumentation mit Matic generieren.

https://github.com/mattyod/matic

Generieren von HTML

Matic So installieren Sie Node.js müssen installieren: http://nodejs.org/

Führen Sie unter Windows CMD

Installieren Jade diesen Befehl ausführen: npm install -g jade

Öffnen Sie die heruntergeladene Matic-Ordner von Github: cd PATH_TO_FOLDER/matic

Führen Sie den Installationsbefehl: npm install -g

eine Dokumentation Beispielprojekt herunterladen: https://github.com/mattyod/matic-simple-example

Setzen Sie Ihr Schema in den Ordner "Schemata"

Öffnen Sie den Projektordner: cd PATH_TO_PROJECT_FOLDER

Run-Befehl: matic

Sie sollten eine Erfolgsmeldung sehen: Documentation built to ./web/

Answer 6

Es kann in Ihrem Fall nicht sinnvoll sein, da es Ihnen scheint sind eine API nicht zu bauen.

Aber wenn es der Fall war und Sie Java oder JVM (JAX-RS) verwendeten, hätten Sie Swagger verwenden können.

Es ermöglicht, Ihre API in einer JSON-Darstellung (wie WSDL/WADL) zu beschreiben. Und sie bieten eine IHM-Ebene, die diese JSON-Darstellung Ihrer API liest. Hier ist, was Sie bekommen: http://petstore.swagger.wordnik.com/

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