摘要：國外的話國內(nèi)的國內(nèi)開源的非常好用的一款文檔管理系統(tǒng)，安裝也非常方便，只需將源代碼放到項(xiàng)目目錄下自動(dòng)安裝運(yùn)行即可，不要要注意版本必須大于界面簡潔功能強(qiáng)大的阿里的接口管理工具，開源免費(fèi)，接口自動(dòng)化，數(shù)據(jù)自動(dòng)生成，自動(dòng)化測試，企業(yè)級(jí)管理。

在項(xiàng)目中，需要協(xié)同開發(fā)，所以會(huì)寫許多API文檔給其他同事，以前都是寫一個(gè)簡單的TXT文本或Word文檔，口口相傳，這種方式比較老土了，所以，需要有個(gè)api管理系統(tǒng)專門來管理這些api，從網(wǎng)上找了許多比較好的開源文檔管理系統(tǒng)，可以應(yīng)用到項(xiàng)目中。

1、國外的話Swagger
swagger-ui

2、國內(nèi)的Showdoc
國內(nèi)開源的非常好用的一款A(yù)PI文檔管理系統(tǒng)，安裝也非常方便，只需將源代碼放到項(xiàng)目目錄下自動(dòng)安裝運(yùn)行即可，不要要注意PHP版本必須大于5.3.

3、界面簡潔功能強(qiáng)大的EOAPI

4、阿里的RAP
Web API management, free and open sourced, mock data generator, auto test, made by Alibaba, using by 1000+ corporations! Web接口管理工具，開源免費(fèi)，接口自動(dòng)化，MOCK數(shù)據(jù)自動(dòng)生成，自動(dòng)化測試，企業(yè)級(jí)管理。阿里媽媽MUX團(tuán)隊(duì)出品！阿里巴巴都在用！1000+公司的選擇！一直被抄襲，從未被超越 :3 http://rapapi.net

5、postMan

6、docute: 無需編譯的文檔撰寫工具
像 gitbook 之類的工具需要編譯后發(fā)布，而 docute 讓你直接寫 markdown 文件作為文檔來顯示而不需要編譯成 html 這一步，你的文檔目錄里只需要一個(gè)首頁 index.html 和你的配置文件 config.js。

docute 會(huì)直接渲染這些 markdown 文件為一個(gè)單頁應(yīng)用。配合 github pages 發(fā)布到 ./docs 目錄效果更佳，當(dāng)然發(fā)布到任何地方都可以。

docute 的文檔: https://docute.js.org/#/zh-Hans/ (基于 Vue)

Github 項(xiàng)目：https://github.com/egoist/docute

7、SmartWiki 接口文檔在線管理系統(tǒng)

8、SosoApi
SosoApi,編輯Swagger UI的神器

9、CrapApi開源接口管理系統(tǒng)演示地址

CrapApi：一個(gè)由angularjs+bootstrap+springMVC搭建的高性能的免費(fèi)開源的API接口、文檔管理系統(tǒng)（應(yīng)用接口管理系統(tǒng)）

GitHub源碼地址：https://github.com/EhsanTang/...
碼云源碼地址：http://git.oschina.net/CrapAp...

主要功能：api接口管理、數(shù)據(jù)字典管理、接口數(shù)據(jù)模擬、接口文檔管理（支持markdown、kindereditor等編輯器）、支持本地部署或在線使用、支持通過建表語句導(dǎo)入數(shù)據(jù)字典...

其他功能：項(xiàng)目管理、用戶管理、模塊管理、接口管理、接口版本管理、接口拷貝、接口文檔pdf下載、接口mock、模塊加密訪問、
接口在線調(diào)試、數(shù)據(jù)字典管理、數(shù)據(jù)字典加密訪問多管理員、多權(quán)限、多角色管理、自定義菜單、自定義網(wǎng)站樣式、文檔留言、
錯(cuò)誤碼管理、接口排序、DOC、PDF、TEXT、EXCEL等資源管理、支持版本號(hào)控制、文檔內(nèi)容檢索、操作日志記錄、
根據(jù)日志恢復(fù)數(shù)據(jù)、markdown編輯器、kindeditor編輯器、angularjs編輯器、Lucene搜索、項(xiàng)目成員管理...

站點(diǎn)使用地址：http://api2.crap.cn
效果圖：

10、 TeaKKi
這個(gè)WIKI用來寫文檔也不錯(cuò)~
TeaKKi == team wiki, https://teakki.com 超越了wiki, 在wiki基礎(chǔ)上支持團(tuán)隊(duì)知識(shí)協(xié)作

11、Web API文檔生成工具apidoc

這個(gè)需要在編輯后生成靜態(tài)的HTML頁面，然后上傳到服務(wù)器。

工具名稱：apiDoc
Git地址：https://github.com/apidoc/apidoc
項(xiàng)目地址：http://apidocjs.com/
樣例項(xiàng)目：http://apidocjs.com/example_b...
apoDoc是從源碼的注釋中生成RestFul api 文檔，樣子還是蠻漂亮的……

使用apidoc 生成Restful web Api文檔
NodeJS、NPM安裝配置步驟(windows版本)

Apidoc安裝與使用

Windows安裝方法：
1、官網(wǎng)nodejs.org下載Node

2、安裝

3、將npm 替換為淘寶鏡像cnpm

C:UsersAdministrator>npm install -g cnpm --registry=https://registry.npm.taobao.org

4、使用cnpm安裝apidoc

C:UsersAdministrator>cnpm install apidoc -g

安裝的地址：

[apidoc@0.17.5] link C:UsersAdministratorAppDataRoaming
pmapidoc@ -> C:UsersAdministratorAppDataRoaming
pm
ode_modulesapidocinapidoc

C:UsersAdministratorAppDataRoaming
pm
ode_modulesapidoc

監(jiān)控api_doc.json文件改變，然后自動(dòng)生成HTML

watch.js文件，然后node 執(zhí)行該文件

/**
 * watch.js
 * Created by lincoln on 16-1-6.
 */
var gaze = require("gaze");
var exec = require("child_process").exec;
var fs = require("fs")


function init(){
    fs.mkdirSync("./api");
    fs.mkdirSync("./doc");
    createConfigureFile();
    beginWatch();
}
/**
{
  "name": "測試",
  "version": "0.0.1",
  "description": "API文檔測試",
  "title": "API文檔測試",
  "url" : "http://121.41.44.218",
  "sampleUrl" : "http://121.41.44.218",
  "template":{
    "forceLanguage":"zh-cn"
  }
}
*/

function createConfigureFile(){
    var configure = {
      "name": "測試",
      "version": "0.0.1",
      "description": "API文檔測試",
      "title": "API文檔測試",
      "url" : "http://xxxxxx",
      "sampleUrl" : "http://xxx",
      "template":{
        "forceLanguage":"zh-cn"
      }
    }
    fs.writeFileSync("./api/apidoc.json",JSON.stringify(configure));
}

function beginWatch(){
    gaze("./api/*.*",function(error,watcher){
     this.on("all", function(event, filepath) {
        console.log(filepath + " was " + event);
        runGeneartion();
      })
    });
}

function runGeneartion(){
    var com = exec("apidoc -i ./api -o ./doc ")
    com.stdout.on("data", function (data) {
        console.log("生成Api->"+data);
    });

    com.stderr.on("data", function (data) {
        console.log("生成錯(cuò)誤啦->" + data);
    });
}

if(fs.existsSync("./api") && fs.existsSync("./doc")){
    beginWatch();
}else{
    init();
}

安裝gaze包，然后執(zhí)行watch.js文件：

?  apidoc cnpm install gaze
[gaze@*] installed at node_modules/.1.1.2@gaze (14 packages, use 2s, speed 54.93kB/s, json 85.75kB, tarball 0B)
All packages installed (14 packages installed from npm registry, use 2s, speed 54.62kB/s, json 17(85.75kB), tarball 0B)
?  apidoc node watch.js
/WEB/apidoc/api/apidoc.json was changed
生成Api->info: Done.

api參數(shù)：

Usage: C:Program Files
odejs
ode.exe apidoc [options]

Options:
   -f, --file-filters      RegEx-Filter to select files that should be parsed (multiple -f can be used)
   -e, --exclude-filters   RegEx-Filter to select files / dirs that should not be parsed (many -e can b
   -i, --input             Input / source dirname.  [./]
   -o, --output            Output dirname.  [./doc/]
   -t, --template          Use template for output files.  [C:UsersAdministratorAppDataRoaming
pm
   -c, --config            Path to directory containing config file (apidoc.json)  [./]
   -p, --private           Include private APIs in output.  [false]
   -v, --verbose           Verbose debug output.  [false]
   -h, --help              Show this help information.
   --debug                 Show debug messages.  [false]
   --color                 Turn off log color.  [true]
   --parse                 Parse only the files and return the data, no file creation.  [false]
   --parse-filters         Optional user defined filters. Format name=filename
   --parse-languages       Optional user defined languages. Format name=filename
   --parse-parsers         Optional user defined parsers. Format name=filename
   --parse-workers         Optional user defined workers. Format name=filename
   --silent                Turn all output off.  [false]
   --simulate              Execute but not write any file.  [false]
   --markdown              Turn off default markdown parser or set a file to a custom parser.  [true]
   --line-ending           Turn off autodetect line-ending. Allowed values: LF, CR, CRLF.
   --encoding              Set the encoding of the source code. [utf8].  [utf8]

D:codeapi_doc>apidoc -i example/ -o doc/
info: Done.

D:POCOapi_doc>

12、PHP_DOC 實(shí)時(shí)生成 API 文檔
https://segmentfault.com/a/11...

13、Outline
GitHub地址：https://github.com/authing/ou...

截圖：

這個(gè)開源的文檔界面看起來還挺不錯(cuò)。

14、documize/community
GitHub地址：https://github.com/documize/c...

15、線上文檔
①、阿里的 語雀
②、騰訊的 樂享
③、confluence
④、Mindoc

相關(guān)文章：
《移動(dòng)開發(fā)接口及文檔編寫規(guī)范》V1.0