所以我正在尝试记录我正在编写的 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 Schema可以达到这个目的，但在实践中我不确定它是否有效。值得一提的是我希望。

除此之外，我个人的看法是，由于 JSON 主要用于传输对象，因此在客户端使用的语言(Java、C#、各种脚本语言)中记录等效对象可能最有意义——毕竟，这样的对象通常是映射/绑定(bind)到 JSON 并返回。然后您可以使用任何可用的文档工具，例如 Java 的 Javadoc(Perl 的 perldoc，c++ 的 Oxygen 等)。

对于指定接口(interface)，还有 WADL (网络应用描述语言)，这可能会有所帮助。

https://stackoverflow.com/questions/3953692/