Syntax zur Dokumentation der JSON-Struktur

Ich versuche also, das Format des JSON zu dokumentieren, das von einer API zurückgegeben wird, gegen die ich schreibe, und ich möchte wissen, ob es ein beliebtes Format für die Dokumentation der JSON-Struktur gibt.

Hinweis: Ich versuche nicht, etwas zu testen oder zu validieren. Ich verwende dies nur zur Dokumentation. Auch einige Möglichkeiten, Kommentare zu Nichtkonstanten hinzuzufügen (Elemente, die immer mit demselben Wert zurückgegeben werden), wären hilfreich.

Dies ist das nicht ganz durchdachte Schema, das ich derzeit verwende:

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
}

Theoretisch könnte das JSON-Schema diesem Zweck dienen, aber in der Praxis bin ich mir nicht sicher, ob dies der Fall ist. Erwähnenswert hoffe ich.

Abgesehen davon ist meine persönliche Meinung, dass die Dokumentation gleichwertiger Objekte in Sprachclient-Anwendungen (Java, C #, verschiedene Skriptsprachen) am sinnvollsten sein kann, da JSON hauptsächlich zum Übertragen von Objekten verwendet wird. Schließlich werden solche Objekte normalerweise zugeordnet / gebunden zu JSON und zurück. Und dann können Sie alle verfügbaren Dokumentationstools wie Javadoc für Java (Perldoc für Perl, Oxygen für C ++ usw. usw.) verwenden.

Zum Festlegen von Schnittstellen gibt es auch WADL (Web App Description Language), die möglicherweise hilfreich ist.

So generieren Sie eine HTML-Dokumentation aus JSON:

Sie müssen ein Json-Schema generieren. Es gibt diesen Dienst, mit dem Sie den ursprünglichen JSON einfügen und das Schema automatisch generieren können:

http://www.jsonschema.net/

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

https://github.com/mattyod/matic

HTML generieren

Um Matic zu installieren, müssen Sie Node.js installieren: http://nodejs.org/

Führen Sie unter Windows CMD aus

Installieren Sie Jade mit diesem Befehl: npm install -g jade

Öffnen Sie den Ordner "Downloaded Matic" von Github: cd PATH_TO_FOLDER/matic

Führen Sie den Installationsbefehl aus: npm install -g

Laden Sie ein Dokumentationsbeispielprojekt herunter: https://github.com/mattyod/matic-simple-example

Legen Sie Ihr Schema in den Ordner "Schemas"

Öffnen Sie den Projektordner: cd PATH_TO_PROJECT_FOLDER

Führen Sie den Befehl aus: matic

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

Ich bin mir nicht sicher, warum Sie versuchen, JSON zu dokumentieren. Ich kann mir vorstellen, dass Sie versuchen, einen konsistenten Weg zu finden, um einer IDE oder einem Entwickler die Datentypen in Ihrer Notation mitzuteilen.

jsdoc (http://jsdoc.sourceforge.net/#usage) könnte das sein, wonach 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 Sie versuchen, die Struktur Ihrer Daten zu demonstrieren. Sie können sich YAML (http://www.yaml.org/) ansehen. Es ist als lesbares Serialisierungsformat konzipiert, das möglicherweise besser zur Dokumentation Ihrer Datenstruktur geeignet ist.

Ein kurzes Beispiel:

Author:
  name: String
  clicked: Boolean
  created: Integer

Bei einfachen APIs, bei denen jeder JSON-Block nur eine oder zwei Ebenen tief ist, scheint die Dokumentation anhand von Beispielen die gängige Praxis zu sein.

Für komplexere Datenmodelle wie Ihres habe ich jedoch keine gute Lösung gesehen. Es gibt einige Vorschläge für JSON-Schemata, aber das scheint dem Geist von JSON zu widersprechen und scheint zu schwergewichtig für Ihren Zweck, nur zu dokumentieren.

Persönlich finde ich Ihr Schema sehr gut. Mit ein paar kleinen Erweiterungen für optionale und alternative Abschnitte könnte es genauso ausdrucksstark sein wie die Backus-Naur-Form, sehr einfach zu lesen und zu verstehen sein und dem Geist von JSON entsprechen. Vielleicht können wir etwas Schwung hinter andere bringen, um diese "Taycher JSON Grammatikform" (TJGF) zu verwenden!

Sie können eine JSON-Beispielantwort schreiben und diese dann mit Markdown und Docco dokumentieren . Docco gibt einfach zu befolgende HTML-basierte Dokumentation aus.

In Ihrem Fall ist dies möglicherweise nicht hilfreich, da Sie anscheinend keine API erstellen.

Aber wenn dies der Fall wäre und Sie Java oder JVM (JAX-RS) verwenden würden, hätten Sie Swagger verwenden können.

Es ermöglicht die Beschreibung Ihrer API in einer JSON-Darstellung (wie WSDL / WADL). Und sie bieten eine IHM-Schicht, die die JSON-Darstellung Ihrer API liest. Folgendes erhalten Sie: http://petstore.swagger.wordnik.com/

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

Eine einfache, aber effektive Möglichkeit besteht darin, ein JSON-Schema mit einem JSON-Schemagenerator zu erstellen und dann JSON Schema for Humans , ein Python-Dienstprogramm, zum Erstellen einer interaktiven HTML-Dokumentation zu verwenden:

pip install json-schema-for-humans
generate-schema-doc [OPTIONS] SCHEMA_FILE [RESULT_FILE]

Nützliche Referenzen:

1. pypi json-schema-für-menschen seite
2. json-schema-for-human-Dokumentation mit einigen visuellen Beispielen für die Ausgabe

Beachten Sie, dass sich das JSON-Schema derzeit noch im Entwurfszustand befindet, um in Zukunft ein IETF-Standard zu werden.