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应用程序描述语言），这可能会有所帮助。

Answer 2

如何从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打开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）！

Answer 5

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

Answer 6

它可能在您的情况下没用，因为您似乎没有构建API。

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

它允许以JSON表示形式描述您的API（如WSDL / WADL）。它们提供了一个IHM层，用于读取API的JSON表示。您将获得以下内容：http://petstore.swagger.wordnik.com/

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

Answer 7

一种简单而有效的方法是使用JSON schema创建一个JSON schema generator，然后使用Python实用工具JSON Schema for Humans创建html交互式文档：

pip install json-schema-for-humans
generate-schema-doc [OPTIONS] SCHEMA_FILE [RESULT_FILE]

有用的参考文献

：

pypi json-schema-for-humans page
json-schema-for-humans documentation，其中包含一些直观的输出示例

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

用于记录JSON结构的语法

7 个答案: