用於記錄JSON結構的語法

因此，我正在嘗試記錄由api返回的json的格式，我正在寫作，並且我想知道是否有任何流行的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 
}

來源

2010-10-17 Roman A. Taycher

我覺得你的方案其實是一個相當不錯的起點。我打算建議字段的值有限，以使用類似'「mode」：「fast」|的語法「中」| 「slow」，'，其中每個可能的值都明確地以字符串或int或布爾值的形式給出。垂直條'|'在JSON（字符串外）中不合法，所以它的含義是元字符。 – 2015-07-08 22:50:46

理論上JSON Schema可以達到這一目的，但在實踐中，我不知道它。值得一提的是我希望。

除此之外，我個人認爲由於JSON主要用於傳輸對象，所以在語言客戶端使用（Java，C＃，各種腳本語言）中記錄等效對象可能是最有意義的 - 畢竟，這些對象通常被映射/綁定到JSON並返回。然後你可以使用任何可用的文檔工具，比如用於Java的Javadoc（perldoc用於Perl，用於C++的Oxy等等）。

爲了指定接口，還有WADL（Web應用程序描述語言），這可能有所幫助。

來源

2011-01-06 22:20:10 StaxMan

老問題，但 - JSON模式標準的「超模式」部分可以非常全面地記錄鏈接/表單。 – cloudfeet 2013-01-18 15:59:33

你有沒有試過https://github.com/apiaryio/mson？ – hellboy 2014-10-08 06:41:00

我不確定你爲什麼試圖記錄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-10 22:51:37 SnatchFrigate

爲開發人員記錄api。 – 2011-01-11 08:52:59

jsdoc輸出的形狀正是我所要做的，我將它直接放在產生輸出的服務的源文件中。然後，我會在下面提供簡短的示例輸出。約定是需要使用服務的開發人員只需查看源代碼。 – jaydel 2011-01-13 13:18:49

請注意，註釋被禁止在JSON 他們會做出的API，如JavaScript JSON.parse（）來，失敗你仍然可以包括評論，但他們將不得不將其傳送到目的地之前必須從JSON刪除（配置讀卡器， Web客戶端，...） – 2016-09-29 11:54:09

你可以寫一個樣品JSON響應，然後用降價和Docco記錄它。 Docco輸出易於遵循基於HTML的文檔。

來源

2011-01-11 22:33:52

將它從消費和生成JSON的源代碼中解耦出來的一個挑戰是您添加了保持這兩件事情同步的新風險。這對於所有文檔來說當然是一個共同的挑戰，但由於這裏的觀衆是開發人員，所以在代碼中留下示例可能有助於降低這種風險。 – jaydel 2011-01-13 15:46:49

對於每個JSON塊只有一層或兩層深度的簡單API，通過顯示示例進行文檔記錄似乎是常見操作。

但是，對於更復雜的數據模型，比如你的，我還沒有看到任何好的解決方案。有一些JSON模式提案，但是這似乎違背了JSON的精神，並且對於您僅僅記錄文件的目的而言似乎太重量級了。

我個人認爲你的方案非常好。通過一些小的擴展來處理可選的和可選的部分，我認爲它可以與Backus-Naur Form一樣具有表現力，非常容易閱讀和理解，並且符合JSON的精神。也許我們可以利用這個「Taycher JSON語法形式」（TJGF）獲得一些推動力！

來源

2011-10-10 20:39:59

如何從JSON一個HTML文檔：

你需要生成一個Json Schema，有這個服務，你可以粘貼原單JSON和自動生成架構：

http://www.jsonschema.net/

通過手中的模式，您可以使用Matic自動生成HTML文檔。

https://github.com/mattyod/matic

生成HTML

安裝馬蒂奇則需要安裝Node.js的： http://nodejs.org/

在Windows上，運行CMD

安裝玉運行此命令： npm install -g jade

打開從Github上下載馬蒂奇文件夾： 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-11 18:09:58

感謝提Matic。只需要一點，你也可以通過運行來安裝它： npm install -g matic – Mattyod 2013-04-22 16:07:48

我想使用Json Schema來驗證JSON，這是可能的，還是僅用於生成文檔？ – Daryl 2017-01-03 16:45:35

jsonschema.net不再回應可能https://app.quicktype.io/#l=schema可以是有用的 – lrkwz 2018-02-17 19:03:11

因爲它似乎你是不是建立一個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-24 10:56:00

用於記錄JSON結構的語法

回答

相關問題