用于记录JSON结构的语法

Question

所以我试图记录我正在写的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
}

Answer 1

从理论上讲,JSON Schema可以达到这个目的,但在实践中我不确定是否可以.值得一提的是我希望.

除此之外,我个人的观点是,由于JSON主要用于传输对象,因此在语言客户端使用(Java,C#,各种脚本语言)中记录等效对象可能最有意义 - 毕竟,这些对象通常被映射/绑定到JSON然后回来.然后你可以使用任何可用的文档工具,比如Javadoc for Java(Perl的Perloc,C++的Oxygen等).

对于指定接口,还有WADL(Web App描述语言),这可能会有所帮助.

Answer 2

如何从JSON生成HTML文档:

您需要生成一个Json Schema,有这个服务可以粘贴原始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/

Answer 3

我不确定你为什么要尝试记录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

Answer 4

对于每个JSON块只有一层或两层深度的简单API,通过显示示例进行记录似乎是常见的做法.

但是对于像你这样的更复杂的数据模型,我还没有看到任何好的解决方案.有一些JSON模式提议,但这似乎违背了JSON的精神,并且对于仅仅记录文档而言似乎太重了.

就个人而言,我认为你的计划非常好.通过一些小的扩展来处理可选和替代部分,我认为它可以像Backus-Naur Form一样富有表现力,非常容易阅读和理解,并且符合JSON的精神.也许我们可以在其他人身上获得一些动力来使用这个"Taycher JSON语法形式"(TJGF)!