用于记录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
}

从理论上讲，JSON Schema可以达到此目的，但实际上我不确定它是否可以实现此目的。值得一提的是我希望。

除此之外，我个人认为，由于JSON主要用于传输对象，因此在语言客户端使用（Java，C＃，各种脚本语言）中记录等效对象可能更有意义-毕竟，此类对象通常是映射/绑定的到JSON并返回。然后，您可以使用任何可用的文档工具，例如Javadoc for Java（Perldoc for Perl，Oxygen for c ++等）。

对于指定接口，还有WADL（Web应用程序描述语言），这可能会有所帮助。

如何从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

运行安装命令： 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/#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

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

但是，对于像您这样的更复杂的数据模型，我还没有看到任何好的解决方案。有一些JSON模式建议，但这似乎与JSON的精神背道而驰，对于您仅出于文档记录的目的而言似乎过于繁琐。

就个人而言，我认为您的计划非常好。通过一些小的扩展来处理可选部分和替代部分，我认为它可以像Backus-Naur Form一样具有表现力，易于阅读和理解，并且符合JSON的精神。也许我们可以在使用“ Taycher JSON语法表”（TJGF）的背后获得动力！

您可以编写一个示例JSON响应，然后使用Markdown和Docco将其记录下来。Docco输出易于遵循的基于HTML的文档。

由于您似乎没有构建API，因此它可能对您没有用。

但是，如果是这种情况，并且您正在使用Java或JVM（JAX-RS），则可以使用Swagger。

它允许以JSON表示形式（例如WSDL / WADL）描述您的API。它们提供了一个IHM层，该层读取API的JSON表示形式。这是您将得到的：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-schema-for-humans页面
2. json-schema-for-humans文档，其中包含输出的一些直观示例

请记住，到目前为止，JSON Schema仍处于草稿状态，目的是将来成为IETF标准。