用于记录JSON结构的语法 [英] Syntax for documenting JSON structure
问题描述
所以我试图记录我正在写的一个api返回的json的格式，我想知道json结构的文档是否有流行的格式。
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.
注意我不是要测试或验证任何东西，我只是使用这个文档。还有一些方法来向非常量添加注释（项目总是返回w /相同的值）将是很好的。
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.
示例：
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 可以用于此目的，但是实践我不确定它。值得一提的是，我希望。
In theory JSON Schema could serve this purpose, but in practice I am not sure it does. Worth mentioning I hope.
除此之外，我个人认为，由于JSON主要用于传输对象，记录语言客户端使用中的等效对象（Java，C＃各种脚本语言）可能最有意义 - 毕竟，这样的对象通常被映射/绑定到JSON并返回。然后，您可以使用任何可用的文档工具，如Javadoc for Java（Perloc for Perl，Oxygen for c ++等）。
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).
对于指定接口，还有 WADL （Web App描述语言），这可能有帮助。
For specifying interfaces there is also WADL (Web App Description Language), which might help.
这篇关于用于记录JSON结构的语法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
