web-dev-qa-db-ja.com

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
}
jsondocumentationnotation
66
Roman A. Taycher

理論的には JSON Schema はこの目的に役立つ可能性がありますが、実際にはそれが確かではありません。言及する価値があると思います。

これ以外に、私の個人的な意見では、JSONは主にオブジェクトの転送に使用されるため、言語クライアントで使用する同等のオブジェクト（Java、C＃、さまざまなスクリプト言語）を文書化することが最も理にかなっているかもしれません-結局、そのようなオブジェクトは通常マッピング/バインドされますJSONに戻って。そして、Java（perldoc for Perl、Oxygen for c ++ etc）など）のJavadocなど、利用可能なドキュメントツールを使用できます。

インターフェイスを指定するために [〜＃〜] wadl [〜＃〜] （Webアプリ記述言語）もあります。

32
StaxMan

JSONからHTMLドキュメントを生成する方法：

Json Schema を生成する必要があります。元のJSONを貼り付けてスキーマを自動生成できるこのサービスがあります。

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からダウンロードしたMaticフォルダーを開きます：cd PATH_TO_FOLDER/matic

インストールコマンドを実行します：npm install -g

ドキュメントのサンプルプロジェクトをダウンロードします。 https://github.com/mattyod/matic-simple-example

スキーマをフォルダー「schemas」に入れます

プロジェクトフォルダーを開きます：cd PATH_TO_PROJECT_FOLDER

コマンドを実行：matic

成功メッセージが表示されます：Documentation built to ./web/

14
Carlos Oliveira

JSONをドキュメント化しようとしている理由がわかりません。IDEまたは開発者に表記上のデータ型を伝える一貫した方法を見つけようとしていると思います。

jsdoc（http://jsdoc.sourceforge.net/#usage）があなたが探しているものかもしれません。

例えば：

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

各JSONチャンクの深さが1または2レベルしかない単純なAPIの場合、例を示すことで文書化するのが一般的な方法のようです。

しかし、あなたのようなより複雑なデータモデルの場合、良い解決策は見当たりません。 JSONスキーマの提案がいくつかありますが、それはJSONの精神に反するようであり、単に文書化するという目的には重すぎるようです。

個人的には、あなたのスキームはとても良いと思います。オプションおよび代替セクションを処理するためのいくつかの小さな拡張機能を使用すると、Backus-Naur Formと同じくらい表現力があり、非常に読みやすく、理解しやすく、JSONの精神に沿ったものになると思います。この「Taycher JSON Grammar Form」（TJGF）を使用するために、他の人に遅れをとることができるかもしれません！

5
Eamonn O'Brien-Strain

サンプルJSON応答を作成し、Markdownおよび Docco を使用して文書化できます。 Doccoの出力は、HTMLベースのドキュメントに従うのが簡単です。

3
Josh Schumacher

APIを作成していないように見えるので、あなたの場合には役に立たないかもしれません。

しかし、そのような場合にJavaまたはJVM（JAX-RS）を使用していれば、Swaggerを使用できた可能性があります。

APIをJSON表現（WSDL/WADLなど）で記述することができます。そして、APIのJSON表現を読み取るIHMレイヤーを提供します。ここにあなたが得るものがあります： http://petstore.swagger.wordnik.com/

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

3
Sebastien Lorber