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

知乎使用者2015-03-29 13:19:09

你需要Sphinx！！！

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

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

更為方便的是，網上有一個網站提供rst的線上編輯器，地址為

http：//

rst。ninjs。org/

，你可以像使用編輯器一樣來編寫你的API文件，然後複製到Sphinx專案中去就行了。

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

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

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

陳振宇2015-03-29 16:41:35

http：//

apiary。io

原來API文件還可以這麼屌！Apiary還開源了APIBlueprint，可以用markdown寫文件，還可以透過中間工具釋出到Github pages。

第七星塵2015-11-27 23:28:41

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/0

5/2007。html

使用線上的ShowDoc

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

Nate2018-11-26 15:42:12

推薦你：易文件，可以很方便的寫出專業漂亮的API文件，使用手冊，還支援線上介面測試

進位制資料2019-09-06 17:51:58

想寫出好看的API介面文件，一些實用的工具能夠對我們有很多的幫助，這裡我找了一些比較實用的工具，推薦給大家。

1、Swagger

Swagger 是一套圍繞OpeanAPI規範構建的開源工具，便於構建和使用REST API。Swagger UI - 讓OpenAPI規範以互動式API文件呈現，是一個簡單的Restful API 測試和文件工具。透過讀取JSON 配置顯示API。專案本身僅僅也只依賴一些 html，css。js靜態檔案。幾乎可以放在任何Web容器上使用。Swagger可以完整地定義一個介面的內容，包括各個引數、返回值的具體結構、型別，Swagger Editor可以實時進行編輯並在線除錯。編輯好的API可以匯出為json檔案，使用Swagger UI開啟即可以看到更美觀的介面文件。

2、Spring REST Docs

Spring REST Docs可幫助您記錄RESTful服務。它結合了使用Asciidoctor編寫的手寫文件和使用Spring MVC Test生成的自動生成的片段。這種方法使您免受Swagger等工具生成的文件的限制。它可以幫助您生成準確，簡潔和結構良好的文件。然後，該文件允許您的使用者輕鬆獲取所需資訊。