JSON 구조 문서화를위한 구문

JSON 구조 문서화를위한 구문

---

그래서 나는 내가 쓰고있는 api가 반환하는 json의 형식을 문서화하려고 노력하고 있는데 json 구조의 문서화에 대해 인기있는 형식이 있는지 알고 싶습니다.

참고 나는 아무것도 테스트하거나 유효성을 검사하려는 것이 아니라 문서화를 위해 이것을 사용하고 있습니다. 또한 상수가 아닌 항목 (항상 동일한 값으로 반환되는 항목)에 주석을 추가하는 몇 가지 방법이 좋습니다.

이것은 내가 현재 사용하는 완전히 생각되지 않은 계획입니다.

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.

예:

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 스키마 가이 목적을 달성 할 수 있지만 실제로는 그렇게 할 수 있는지 잘 모르겠습니다. 나는 희망을 언급 할 가치가있다.

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/

---

I'm unsure to why you're trying to document JSON, I can guess your trying to find a consistent way to tell an IDE or a developer the data types on your notation.

jsdoc (http://jsdoc.sourceforge.net/#usage) might be what your are looking for.

for example:

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

Alternatively if your trying to demonstrate the structure of your data. You could look at YAML (http://www.yaml.org/), it's designed to be a human readable serialisation format which maybe be better suited for documenting your data structure.

A quick example:

Author:
  name: String
  clicked: Boolean
  created: Integer

---

For simple APIs where each JSON chunk is only one or two levels deep, then documenting by showing examples seems to be the common practice.

However for more complex data models such as yours, I have not seen any good solution. There are some JSON schema proposals, but that seems to go against the spirit of JSON, and seems too heavyweight for your purpose of just documenting.

Personally, I think your scheme is very good. With a few small extensions to handle optional and alternative sections I think it could be just as expressive as Backus-Naur Form, be very easy to read and understand, and be in keeping with the spirit of JSON. Maybe we can get some momentum behind others to use this "Taycher JSON Grammar Form" (TJGF)!

---

You could write a sample JSON response and then document it using Markdown and Docco. Docco outputs easy to follow HTML based documentation.

---

It may not be useful in your case since it seems you are not building an API.

But if it was the case and you were using Java or JVM (JAX-RS), you could have used Swagger.

It permits to describes your API in a JSON representation (like WSDL/WADL). And they provide an IHM layer that reads that JSON representation of your API. Here is what you will get: http://petstore.swagger.wordnik.com/

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

참고URL : https://stackoverflow.com/questions/3953692/syntax-for-documenting-json-structure