So I'm trying to document the format of the json returned by an api I am writing against and I'd like to know if there is any popular format for the documentation of json structure.
Note I'm not trying to to test or validate anything, I'm just using this for documentation. Also some ways to add comments to non-constants(items always returned w/ the same value) would be nice.
This the not totally thought out scheme I'm currently using:
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.
example:
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 }
JSON syntax is derived from JavaScript object notation syntax: Data is in name/value pairs. Data is separated by commas. Curly braces hold objects.
JSON has the following syntax. Objects are enclosed in braces ( {} ), their name-value pairs are separated by a comma ( , ), and the name and value in a pair are separated by a colon ( : ). Names in an object are strings, whereas values may be of any of the seven value types, including another object or an array.
A JSON object contains zero, one, or more key-value pairs, also called properties. The object is surrounded by curly braces {} . Every key-value pair is separated by a comma. The order of the key-value pair is irrelevant.
In theory JSON Schema could serve this purpose, but in practice I am not sure it does. Worth mentioning I hope.
Other than this, my personal opinion is that since JSON is predominantly used for transferring objects, documenting equivalent objects in language client uses (Java, C#, various scripting languages) may make most sense -- after all, such objects usually are mapped/bound to JSON and back. And then you can use whatever documentation tools are available, like Javadoc for Java (perldoc for Perl, Oxygen for c++ etc etc).
For specifying interfaces there is also WADL (Web App Description Language), which might help.
How to generate a HTML Documentation from JSON:
You will need to generate a Json Schema, there is this service that you can paste the orginal JSON and auto generate the Schema:
http://www.jsonschema.net/
With the schema in hands you can auto generate the HTML Documentation using Matic.
https://github.com/mattyod/matic
Generating HTML
To Install Matic you will need install Node.js: http://nodejs.org/
On Windows, run CMD
Install Jade running this command: npm install -g jade
Open the Downloaded Matic folder from Github: cd PATH_TO_FOLDER/matic
Run the install command: npm install -g
Download a documentation example project: https://github.com/mattyod/matic-simple-example
Put your schema in the folder "schemas"
Open the project folder: cd PATH_TO_PROJECT_FOLDER
Run command: matic
You should see a success message: Documentation built to ./web/
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With