用于记录 JSON 结构的语法

Syntax for documenting JSON structure

提问by Roman A. Taycher

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.

所以我试图记录我正在编写的 api 返回的 json 格式，我想知道是否有任何流行的 json 结构文档格式。

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.

example:

例子：

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
}

采纳答案by StaxMan

In theory JSON Schemacould serve this purpose, but in practice I am not sure it does. Worth mentioning I hope.

理论上JSON Schema可以用于此目的，但在实践中我不确定它是否确实如此。值得一提，我希望。

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).

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

For specifying interfaces there is also WADL(Web App Description Language), which might help.

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

回答by Carlos Oliveira

How to generate a HTML Documentation from JSON:

如何从 JSON 生成 HTML 文档：

You will need to generate a Json Schema, there is this service that you can paste the orginal JSON and auto generate the Schema:

您需要生成一个Json Schema，有这个服务，您可以粘贴原始 JSON 并自动生成 Schema：

http://www.jsonschema.net/

http://www.jsonschema.net/

With the schema in hands you can auto generate the HTML Documentation using Matic.

掌握了架构后，您可以使用 Matic 自动生成 HTML 文档。

https://github.com/mattyod/matic

https://github.com/mattyod/matic

Generating HTML

生成 HTML

To Install Matic you will need install Node.js: http://nodejs.org/

要安装 Matic，您需要安装 Node.js：http: //nodejs.org/

On Windows, run CMD

在 Windows 上，运行 CMD

Install Jade running this command: npm install -g jade

运行以下命令安装 Jade： npm install -g jade

Open the Downloaded Matic folder from Github: cd PATH_TO_FOLDER/matic

从 Github 打开下载的 Matic 文件夹： cd PATH_TO_FOLDER/matic

Run the install command: npm install -g

运行安装命令： npm install -g

Download a documentation example project: https://github.com/mattyod/matic-simple-example

下载文档示例项目：https: //github.com/mattyod/matic-simple-example

Put your schema in the folder "schemas"

将您的架构放在文件夹“架构”中

Open the project folder: cd PATH_TO_PROJECT_FOLDER

打开项目文件夹： cd PATH_TO_PROJECT_FOLDER

Run command: matic

运行命令： matic

You should see a success message: Documentation built to ./web/

您应该会看到一条成功消息： Documentation built to ./web/

回答by SnatchFrigate

I'm unsure to why you're trying to document JSON, I can guess your trying to find a consistent way to tell an IDE or a developer the data types on your notation.

我不确定您为什么要尝试记录 JSON，我猜您是在尝试找到一种一致的方法来告诉 IDE 或开发人员您的表示法中的数据类型。

jsdoc (http://jsdoc.sourceforge.net/#usage) might be what your are looking for.

jsdoc (http://jsdoc.sourceforge.net/#usage) 可能是您正在寻找的。

for example:

例如：

{
   /**
     * 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
}

Alternatively if your trying to demonstrate the structure of your data. You could look at YAML (http://www.yaml.org/), it's designed to be a human readable serialisation format which maybe be better suited for documenting your data structure.

或者，如果您试图展示数据的结构。您可以查看 YAML (http://www.yaml.org/)，它被设计为一种人类可读的序列化格式，可能更适合记录您的数据结构。

A quick example:

一个简单的例子：

Author:
  name: String
  clicked: Boolean
  created: Integer

回答by Eamonn O'Brien-Strain

For simple APIs where each JSON chunk is only one or two levels deep, then documenting by showing examples seems to be the common practice.

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

However for more complex data models such as yours, I have not seen any good solution. There are some JSON schema proposals, but that seems to go against the spirit of JSON, and seems too heavyweight for your purpose of just documenting.

但是，对于像您这样的更复杂的数据模型，我还没有看到任何好的解决方案。有一些 JSON 模式建议，但这似乎与 JSON 的精神背道而驰，而且对于您仅用于记录的目的来说似乎过于重量级。

Personally, I think your scheme is very good. With a few small extensions to handle optional and alternative sections I think it could be just as expressive as Backus-Naur Form, be very easy to read and understand, and be in keeping with the spirit of JSON. Maybe we can get some momentum behind others to use this "Taycher JSON Grammar Form" (TJGF)!

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

回答by Sebastien Lorber

It may not be useful in your case since it seems you are not building an API.

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

But if it was the case and you were using Java or JVM (JAX-RS), you could have used Swagger.

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

It permits to describes your API in a JSON representation (like WSDL/WADL). And they provide an IHM layer that reads that JSON representation of your API. Here is what you will get: http://petstore.swagger.wordnik.com/

它允许以 JSON 表示（如 WSDL/WADL）描述您的 API。他们提供了一个 IHM 层来读取 API 的 JSON 表示。这是您将获得的：http: //petstore.swagger.wordnik.com/

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

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

回答by Josh Schumacher

You could write a sample JSON response and then document it using Markdown and Docco. Docco outputs easy to follow HTML based documentation.

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

回答by Diego

A simple but effective way is to create a JSON schemawith a JSON schema generatorand then use JSON Schema for Humans, a Python utility to create html interactive documentation:

一个简单但有效的方法是使用JSON 模式生成器创建一个JSON 模式，然后使用JSON Schema for Humans，一个 Python 实用程序来创建 html 交互式文档：

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

Useful references:

有用的参考：

1. pypi json-schema-for-humans page
2. json-schema-for-humans documentationthat includes some visual examples of the output

1. pypi json-schema-for-humans 页面
2. json-schema-for-humans 文档，其中包括一些输出的可视化示例

Keep in mind the JSON Schema is still in Draft state as of now, with the aim of becoming a IETF standard in the future.

请记住，JSON Schema 目前仍处于草案状态，其目标是在未来成为 IETF 标准。