85

因此，我正在尝试记录我正在编写的 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
}
4

7 回答 7

40

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

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

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

于 2011-01-06T22:20:10.850 回答
15

如何从 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 打开下载的 Matic 文件夹： cd PATH_TO_FOLDER/matic

运行安装命令： npm install -g

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

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

打开项目文件夹： cd PATH_TO_PROJECT_FOLDER

运行命令： matic

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

于 2013-04-11T18:09:58.597 回答
8

我不确定你为什么要记录 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
于 2011-01-10T22:51:37.227 回答
5

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

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

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

于 2011-10-10T20:39:59.230 回答
3

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

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

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

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

于 2013-04-24T10:56:00.953 回答
3

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

于 2011-01-11T22:33:52.567 回答
2

一种简单但有效的方法是使用 JSON 模式生成器创建JSON模式，然后使用JSON Schema for Humans，这是一个 Python 实用程序来创建 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 标准。

于 2020-05-28T08:37:20.637 回答