JSON 구조를 문서화하기 위한 구문

JSON 구조를 문서화하기 위한 구문

그래서 제가 쓰고 있는 api에 의해 반환된 json의 포맷을 문서화하려고 하는데, json structure에 대한 문서화가 인기 있는 포맷이 있는지 알고 싶습니다.

참고로 저는 테스트나 검증을 하려는 것이 아니라 문서화를 위해 이것을 사용하고 있습니다.또한 비정수(항상 같은 값으로 반환되는 항목)에 주석을 추가하는 방법이 좋습니다.

이것은 현재 사용하고 있는 계획과는 완전히 다른 것입니다.

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 Schema가 이 목적에 도움이 될 수 있지만 실제로는 도움이 될 수 있을지 모르겠습니다.언급할 가치가 있기를 바랍니다.

또, JSON은 오브젝트 전송에 주로 사용되고 있기 때문에, 동등한 오브젝트를 언어 클라이언트의 사용법(Java, C#, 다양한 스크립트 언어)으로 문서화하는 것이 가장 타당하다고 생각합니다.결국, 이러한 오브젝트는 보통 JSON에 매핑/바인드 되어 있습니다.Java용 Javadoc(Perl용 perldoc, c++용 산소 등) 등 사용 가능한 문서 도구를 사용할 수 있습니다.

인터페이스를 지정하기 위해 WADL(Web App Description Language)도 있어 도움이 될 수 있습니다.

JSON에서 HTML 문서를 생성하는 방법:

Json Schema를 생성해야 합니다. Orginal JSON을 붙여넣고 Schema를 자동으로 생성할 수 있는 서비스가 있습니다.

http://www.jsonschema.net/

스키마를 사용하면 Matic을 사용하여 HTML 문서를 자동으로 생성할 수 있습니다.

https://github.com/mattyod/matic

HTML 생성 중

Matic을 설치하려면 Node.js를 설치해야 합니다.http://nodejs.org/

Windows에서 CMD를 실행합니다.

다음 명령을 실행하여 Jade를 설치합니다.npm install -g jade

Github에서 Downloaded Matic 폴더를 엽니다.cd PATH_TO_FOLDER/matic

install 명령을 실행합니다.npm install -g

문서 예시 프로젝트 다운로드:https://github.com/mattyod/matic-simple-example

스키마를 "schemas" 폴더에 넣습니다.

프로젝트 폴더를 엽니다.cd PATH_TO_PROJECT_FOLDER

실행 명령:matic

성공 메시지가 나타납니다.Documentation built to ./web/

왜 JSON을 문서화하려고 하는지 잘 모르겠습니다. IDE 또는 개발자에게 표기법에 있는 데이터 유형을 알려주는 일관된 방법을 찾으려는 것 같습니다.

jsdoc(http://jsdoc.sourceforge.net/#http://http://jsdoc.sourceforge.net/)이 필요한 경우가 있습니다.

예를 들어 다음과 같습니다.

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

또는 데이터 구조를 시연하려고 하는 경우.YAML(http://www.yaml.org/),은 데이터 구조를 문서화하는 데 적합한 사람이 읽을 수 있는 시리얼라이제이션 포맷으로 설계되어 있습니다.

간단한 예:

Author:
  name: String
  clicked: Boolean
  created: Integer

각 JSON 청크의 깊이가 1~2레벨에 불과한 단순한 API의 경우 예를 들어 문서화하는 것이 일반적인 방법인 것 같습니다.

하지만 귀사와 같은 복잡한 데이터 모델의 경우, 저는 좋은 솔루션을 보지 못했습니다.JSON 스키마 제안도 있습니다만, 그것은 JSON의 정신에 반하는 것 같고, 단지 문서화하는 것을 목적으로 하기에는 너무 무거운 것 같습니다.

개인적으로 당신의 계획은 매우 좋다고 생각합니다.옵션 섹션과 대체 섹션을 처리하기 위한 몇 가지 작은 확장을 통해 Backus-Naur Form과 같이 표현력이 풍부하고 읽기 쉽고 이해하기 쉬우며 JSON의 정신에 부합할 수 있다고 생각합니다.이 「Taycher JSON Grammar Form」(TJGF)을 사용할 수 있는 탄력을 얻을 수 있을지도 모릅니다.

샘플 JSON 응답을 작성한 후 Markdown 및 Docco를 사용하여 문서화할 수 있습니다.Docco는 HTML 기반의 매뉴얼을 따르기 쉽게 출력합니다.

API를 구축하지 않은 것 같기 때문에 도움이 되지 않을 수 있습니다.

단, Java 또는 JVM(JAX-RS)을 사용하고 있다면 Swagger를 사용할 수 있습니다.

API를 JSON 표현(WSDL/WADL 등)으로 기술할 수 있습니다.또한 API의 JSON 표현을 읽는 IHM 레이어를 제공합니다.http://petstore.swagger.wordnik.com/ 를 참조해 주세요.

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

간단하지만 효과적인 방법은 JSON 스키마 생성기를 사용하여 JSON 스키마를 만든 다음 Python 유틸리티인 JSON Schema for Humans를 사용하여 html 대화형 문서를 작성하는 것입니다.

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

유용한 참고 자료:

1. pypi json-for-private 페이지
2. 출력의 시각적 예를 포함한 json-for-for-for-for-for-for-for-for-for-f

JSON Schema는 향후 IETF 표준이 되는 것을 목표로 현시점에서는 Draft 상태에 있습니다.

언급URL : https://stackoverflow.com/questions/3953692/syntax-for-documenting-json-structure