如何才能寫出簡潔好看的API文檔，有沒有開源框架可以用？

01-05

本人正在做一個開放平台，需要為本平台寫一些API文檔。我曾經試圖用markdown來寫，但是markdown對code模塊，table支持不好，也不支持一些人性化的設置。是需要手寫CSS，html嗎？但是我不是一個專業的前端開發人員，有沒有開源框架可以用？
我覺得寫的好看的API文檔：LeanCloud 文檔

我記得github的markdown對code和table的支持都挺好啊

ShowDoc是什麼

每當接手一個他人開發好的模塊或者項目，看著那些沒有寫注釋的代碼，我們都無比抓狂。文檔呢？！文檔呢？！Show me the doc ！！

程序員都很希望別人能寫技術文檔，而自己卻很不希望要寫文檔。因為寫文檔需要花大量的時間去處理格式排版，想著新建的word文檔放在哪個目錄等各種非技術細節。

word文檔零零散散地放在團隊不同人那裡，需要文檔的人基本靠吼，吼一聲然後上qq或者郵箱接收對方丟過來的文檔。這種溝通方式當然可以，只是效率不高。

ShowDoc就是一個非常適合IT團隊的在線文檔分享工具，它可以加快團隊之間溝通的效率。

它可以用來做什麼

API文檔（查看Demo）
隨著移動互聯網的發展，BaaS（後端即服務）越來越流行。服務端提供API，APP端或者網頁前端便可方便調用數據。用ShowDoc可以非常方便快速地編寫出美觀的API文檔。
數據字典（查看Demo）
一份好的數據字典可以很方便地向別人說明你的資料庫結構，如各個欄位的釋義等。
說明文檔
你完全可以使用showdoc來編寫一些工具的說明書。也可以編寫一些技術規範說明文檔以供團隊查閱

它都有些什麼功能

分享與導出
- 響應式網頁設計，可將項目文檔分享到電腦或移動設備查看。同時也可以將項目導出成word文件，以便離線瀏覽。
許可權管理
- 公開項目與私密項目
  ShowDoc上的項目有公開項目和私密項目兩種。公開項目可供任何登錄與非登錄的用戶訪問，而私密項目則需要輸入密碼驗證訪問。密碼由項目創建者設置。
- 項目轉讓
  項目創建者可以自由地把項目轉讓給網站的其他用戶。
- 項目成員
  
  你可以很方便地為ShowDoc的項目添加、刪除項目成員。項目成員可以對項目進行編輯，但不可轉讓或刪除項目（只有項目創建者才有許可權）
編輯功能
- markdown編輯
  ShowDoc採用markdown編輯器，無論是編輯還是閱讀體驗都極佳很棒。如果你不了解Markdown，請在搜索引擎搜索」認識與入門 Markdown」
- 模板插入
  在ShowDoc的編輯頁面，點擊編輯器上方的按鈕可方便地插入API介面模板和數據字典模板。插入模板後，剩下的就是改動數據了，省去了很多編輯的力氣。
- 歷史版本
  ShowDoc為頁面提供歷史版本功能，你可以方便地把頁面恢復到之前的版本。

部署到自己的伺服器

ShowDoc部署手冊
請參考：http://blog.star7th.com/2016/05/2007.html

使用在線的ShowDoc

如果你沒有自己的伺服器，但又想使用ShowDoc作為分檔分享工具，你可以使用在線的ShowDoc ShowDoc

你需要python的markdown模塊，在擴展里有你想要的東西

如果是 JavaScript，推薦一個文檔生成工具 FireDoc，基於 YUIDoc 進行了大幅改善：fireball-x/firedoc · GitHub

可以使用模板直接輸出 HTML 頁面，也可以輸出 markdown 文件。

是我們為自己的遊戲引擎項目 Fireball http://fireball-x.com/ 的文檔生成打造的，相比 YUIDoc 更適用於規模較大和較為複雜的工程化項目。開發者是 @Yorkie

Swagger：Rest API的描述語言 - 用心閣的文章 - 知乎專欄

LeanCloud 的文檔項目是開源的：GitHub - leancloud/docs: LeanCloud Documentation

如果你喜歡類似的結構可以 fork 一份自己去改。

http://apiary.io 原來API文檔還可以這麼屌！Apiary還開源了APIBlueprint，可以用markdown寫文檔，還可以通過中間工具發布到Github pages。

你需要Sphinx！！！

Python的官方文檔就是用這個寫的。不過注意這個Sphinx是一個文檔編寫工具而不是那個有名的全文檢索引擎。

Sphinx使用reStructuredText 標記語法（和其他一些語法）來提供文檔控制。reStructuredText 和Markdown類似，但是功能更為強大。

更為方便的是，網上有一個網站提供rst的在線編輯器，地址為http://rst.ninjs.org/，你可以像使用編輯器一樣來編寫你的API文檔，然後複製到Sphinx項目中去就行了。

最後make html一下就生成了靜態網頁的文檔，還能選擇或者自定義模板。

參見：使用 sphinx 製作簡潔而又美觀的文檔

注意官網被牆了，要翻牆才能上，但是網上有基本翻譯好的文檔。

http://Swagger.io

試試

Swagger Editor

簡單的文檔當然是markdown最快，至於覺得table難打，請用http://tablesgenerator.com。

當然，markdown蛋疼的地方我也覺得很煩，真不爽的話自己寫一個解析器如何，擴展點好玩的語法。

假如markdown解析器不想寫，咱們還能學reStructuredText，這貨和markdown語法倒是接近，不過功能豐富太多了。用sphinx就能快速生成各種格式，sublime在裝插件後，表格什麼的完全不同自己打。想看效果的話，移步http://readthedocs.org。

再不濟的話，用office吧。

api不僅要能看，還要能測，這樣才能持續維護。

個人覺得Swagger, RAML都是不錯的選擇，特別是配套的editor和designer, 讓其api在完成之後不單能看還能測！

不過raml到1.0了，很多第三方庫仍舊停留在0.8. 而swagger則是到2.0遲遲不動．

另外，如果是新開發api, 又要寫文檔，又要寫實現就比較煩人了．所以有一些框架會將swagger或raml整合，將api的實現集成在一起．這樣的有很多，這裡推薦一個俺自己寫的框架，pingf/falsy，如果你用python開發的可以試試，還是相當清爽的～（當然其本身的文檔暫時還不太全，不過demo文件夾下有很多現成可用的例子咯）

之前花了一個星期自己做了個：jamesruan/ebony · GitHub

當然，這個本來是用做某個網站的前端框架的。

其組件之一ML，就是代替Markdown的（語法更簡單更嚴謹，功能更強大，就是寫起來更醜陋，感覺在寫TeX）。內部實現用了peg.js生成了叫JHTML的AST，然後再用這個AST重新生成HTML，同時也等於做了XSS防禦。

ML使用語義級別的標籤，表格基本等於寫HTML（複雜的跨欄表頭均可以生成），code高亮，數學公式，圖文混排，emoji都有了。

ML展示（此頁面的HTML均由ML生成）+ 手冊：

The Complete Manual of the Markup Language

API 重在設計上，如果有一套通用 API 設計語言，如 Swagger，API Blueprint, RAML。設計者、開發者、使用者之間通過這套語言來溝通，就無所謂文檔好看了。推薦看這裡：http://www.mikestowe.com/blog/2014/07/raml-vs-swagger-vs-api-blueprint.php

http://apidocjs.com/

比較好用的是swagger-ui, 可以使用swagger editor來編寫。此外slate api編輯器也不錯。

slate demo(Paracel - API Reference)

以上是編輯器。你想在你的項目中自動生成，那麼得需要相關的插件。我做rails開發的，使用swagger，那麼有swagger docs for rails插件，其他語言的自行搜索。rails項目中apipie rails也不錯。

這裡的編輯器不支持md，自己格式化一下。

#### articles

1. [standard json api](Standard JSON API response format?)

2. [api doc tools](Tools to generate beautiful web API documentation)

#### 我們公司的json格式

```ruby

{

status: "success/fail/error",

code: 404,

msg: "Unable to communicate with database",

data: { # or data: nil

posts: [

{id: 1},

{id: 2}

]

links: {

self: "http://example.com/posts",

next: "http://example.com/posts?page[offset]=2",

last: "http://example.com/posts?page[offset]=10"

}

```

#### 相關鏈接

1. [slate](tripit/slate · GitHub)

2. [apipie rails](Apipie/apipie-rails · GitHub)

3. [swagger ui](https://github.com/swagger-api/swagger-ui)

4. [swagger editor](Swagger Editor)

5. [air blue print](https://apiblueprint.org/)

6. [api ary](Apiary — Home)

7. [swagger docs for rails](richhollis/swagger-docs · GitHub)

8. [api taster for test](fredwu/api_taster · GitHub)

AsciiDoctor，你知道擁有。我寫了個文檔，我領導說我的排版水平和出書了，其實我只是用來簡單的 AsciiDoc 而已。呵呵

Doxygen: Main Page

Doxygen是一種開源跨平台的，以類似JavaDoc風格描述的文檔系統，完全支持C、C++、Java、Objective-C和IDL語言，部分支持PHP、C#。注釋的語法與Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以從一套歸檔源文件開始，生成HTML格式的在線類瀏覽器，或離線的LATEX、RTF參考手冊。

我喜歡Android user guide的排版，怎麼做到呢？或者微軟的教程也是非常漂亮整潔

swagger ，還能調試 API，我們在用。

demo：http://petstore.swagger.io