ShowDoc可以幫助用戶編輯API文檔，讓用戶在編輯源代碼的時(shí)候可以更好對(duì)代碼做標(biāo)注，可以讓別人知道你編輯的代碼是什么意思，適合專業(yè)的開(kāi)發(fā)團(tuán)隊(duì)使用，當(dāng)你在編輯新軟件或者是開(kāi)發(fā)新項(xiàng)目的時(shí)候就可以將本軟件安裝到你的開(kāi)發(fā)環(huán)境，在編輯代碼的時(shí)候就可以及時(shí)編輯API，方便其他用戶找到函數(shù)或者是調(diào)用類似的API；ShowDoc提供多種部署方式，可以選擇好動(dòng)安裝，可以選擇自動(dòng)腳本安裝，詳細(xì)的安裝方式可以查看官方提供的教程！

軟件功能

　　1、ShowDoc提供更好的編輯方式，幫助用戶在設(shè)計(jì)API文檔的時(shí)候提供更方便的操作

　　2、可以手動(dòng)編輯API文檔，可以從代碼生成API文檔

　　3、現(xiàn)在很多程序都會(huì)制作API文檔

　　4、通過(guò)查看API文檔就可以知道軟件開(kāi)發(fā)的結(jié)構(gòu)以及相關(guān)模塊的介紹

　　5、讓編程人員可以知道該項(xiàng)目詳細(xì)的編程方式

　　6、當(dāng)你需要編輯API文檔的時(shí)候就可以選擇ShowDoc

　　7、提供豐富的編輯組件，支持composer.json，支持.gitignore

　　8、可以將所有編輯組件添加到你的開(kāi)發(fā)環(huán)境

　　9、可以在直接從你的代碼文件找到可以制作為API文檔的內(nèi)容

　　10、提供verifyCode.php、jquery.zclip等多種調(diào)試組件

軟件特色

　　1、API文檔在很多場(chǎng)合都可以使用，支持對(duì)新開(kāi)發(fā)項(xiàng)目制作API文檔

　　2、支持對(duì)一些的比較復(fù)雜的模塊設(shè)計(jì)介紹類型的API文檔

　　3、也可以對(duì)數(shù)據(jù)字典編輯，方便開(kāi)發(fā)人員查看數(shù)據(jù)庫(kù)結(jié)構(gòu)

　　4、ShowDoc軟件提供良好的markdown編輯器

　　5、輸入的API以及文字內(nèi)容都可以在編輯器顯示

　　6、可以讓客戶知道你開(kāi)發(fā)的詳細(xì)方案

　　7、可以讓編程人員一眼看懂開(kāi)發(fā)邏輯

　　8、相關(guān)的函數(shù)以及代碼都可以通過(guò)ShowDoc世界編輯

　　9、適合在開(kāi)發(fā)大型項(xiàng)目以及團(tuán)隊(duì)項(xiàng)目的時(shí)候制作API文檔

安裝方法

　　1、自動(dòng)腳本安裝

　　官方強(qiáng)烈推薦使用自動(dòng)腳本安裝showdoc。因?yàn)槭褂米詣?dòng)腳本可以省去很多安裝環(huán)境依賴的麻煩，你只需在命令行下執(zhí)行命令即可。自動(dòng)腳本安裝教程：https://www.showdoc.cc/help?page_id=828455960655160 。假如自動(dòng)腳本安裝失敗，你可以考慮手動(dòng)安裝。

　　2、手動(dòng)安裝

　　A:docker安裝

　　如果你不想通過(guò)自動(dòng)腳本，但是又想用docker來(lái)自定義安裝，則可以參考教程https://www.showdoc.cc/help?page_id=65610

　　B:php安裝

　　如果你不想使用自動(dòng)腳本或者docker安裝，showwdoc需要PHP5.3及以上版本，你可以參考這里安裝環(huán)境http://www.showdoc.cc/php 。安裝完P(guān)HP環(huán)境后，下載代碼：https://github.com/star7th/showdoc 。下載完畢后將代碼放到PHP的web目錄。一般來(lái)講，不同系統(tǒng)的web目錄路徑不太一樣。請(qǐng)根據(jù)你安裝的環(huán)境來(lái)定。

　　C：Windows服務(wù)器

　　在php.ini里面把”extension=php_sqlite.dll”和”extension=php_pdo_sqlite.dll”啟用以便開(kāi)啟對(duì)SQlite的支持；也啟用php_mbstring.dll；Linux服務(wù)器則不需要此操作。

使用方法

　　1、提供在線功能，你可以到官方網(wǎng)站注冊(cè)一個(gè)賬號(hào)再使用

　　2、提示建立新項(xiàng)目的方式，你可以輸入項(xiàng)目名字以及輸入項(xiàng)目描述

　　3、假如你的個(gè)性域名設(shè)置為abc,則你的項(xiàng)目地址為www.showdoc.cc/abc

　　4、密碼為空時(shí)，所有人均可以通過(guò)項(xiàng)目地址訪問(wèn)。設(shè)置密碼后，只有項(xiàng)目成員和輸入密碼的人能訪問(wèn)

　　5、進(jìn)入編輯的界面，可以在這里設(shè)計(jì)當(dāng)前的API文檔，可以在下方輸入新內(nèi)容

　　6、點(diǎn)擊插入API接口模板，這里是編輯的界面，你可以查看相關(guān)的模板內(nèi)容

　　7、由于使用markdown編輯器，所以輸入的代碼都可以及時(shí)在軟件上顯示

　　8、插入數(shù)據(jù)字典模板，相關(guān)的內(nèi)容就在這里顯示

　　9、有兩個(gè)工具可以選擇，支持JSON轉(zhuǎn)參數(shù)表格、JSON格式化

　　10、編輯工具都在這里顯示，例如可以添加引用鏈接，也可以添加圖片，也可以插入鏈接

　　11、這里的序號(hào)決定頁(yè)面在項(xiàng)目左側(cè)菜單中的順序，在根目錄或者當(dāng)前目錄下，每個(gè)頁(yè)面按照序號(hào)從小到大排序。在沒(méi)有填寫(xiě)序號(hào)的情況下，showdoc將默認(rèn)補(bǔ)上序號(hào)99，你也可以手動(dòng)設(shè)置為更小的數(shù)字，比如98。那么，該頁(yè)面將比其他99的頁(yè)面都要靠前。以此類推

　　12、在右上方也可以查看軟件的幫助，可以了解編輯格式以及編輯器的語(yǔ)法

使用說(shuō)明

　　對(duì)于寫(xiě)API文檔這件事，雖然說(shuō)文本編輯軟件或者接口管理軟件能在某種程度上提高我們的效率，但我們依然可以試圖借助技術(shù)的力量，更自動(dòng)化地生成API文檔，釋放自己的生產(chǎn)力。

　　為此，showdoc官方提供了一種自動(dòng)化解決方案。在代碼里編寫(xiě)特定格式的程序注釋，然后showdoc通過(guò)讀取這些注釋來(lái)自動(dòng)生成文檔。由于這種方式不跟特定的語(yǔ)言耦合，因此它的使用范圍相當(dāng)廣泛，可用支持c++、java、php、node、python等等常見(jiàn)的主流語(yǔ)言。

　　采用這種方式，盡管我們?cè)诘谝淮翁顚?xiě)注釋的時(shí)候可能會(huì)有些繁瑣，但是它后期帶來(lái)的可維護(hù)性是非常高的。代碼變動(dòng)后，不需要再額外登錄showdoc，直接在代碼里修改注釋即可。同時(shí)自動(dòng)化的腳本也可以加入持續(xù)集成或者某些自動(dòng)化工程里，讓“寫(xiě)API文檔”這件事如”單元測(cè)試”般納入工程工作流里面。

　　windows下使用指引

　　windows無(wú)法直接運(yùn)行sh腳本，需要額外下載軟件。

　　推薦下載git for windows：https://git-scm.com/download/win 下載后直接雙擊安裝即可。

　　如果從官網(wǎng)下載比較慢，可用考慮下載由第三方開(kāi)發(fā)者維護(hù)的國(guó)內(nèi)版(showdoc官方不保證其長(zhǎng)期穩(wěn)定)：

　　https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe

　　以上軟件是基礎(chǔ)環(huán)境。安裝好了后，還需要下載showdoc官方腳本：https://www.showdoc.cc/script/showdoc_api.sh

　　下載后，將showdoc_api.sh放在你的項(xiàng)目目錄下。右擊，選擇編輯。

　　腳本內(nèi)容的前面有兩個(gè)變量，api_key 和 api_token ，這個(gè)需要用戶自行填寫(xiě)。關(guān)于這兩個(gè)變量的取值，請(qǐng)登錄showdoc，進(jìn)入某個(gè)項(xiàng)目的設(shè)置，點(diǎn)擊開(kāi)放API，便可以看到說(shuō)明。showdoc_api.sh生成的文檔會(huì)放進(jìn)你填寫(xiě)的這個(gè)項(xiàng)目里。除了api_key 和 api_token ，還有一個(gè)url變量。如果是使用www.showdoc.cc ，則不需要修改。如果是使用開(kāi)源版showdoc，則需要將地址改為http://xx.com/server/index.php?s=/api/open/fromComments ，其中，別忘記了url里含server目錄。

　　填寫(xiě)完畢，保存。然后直接雙擊運(yùn)行，腳本會(huì)自動(dòng)遞歸掃描本目錄和子目錄的所有文本代碼文件，并生成API文檔。

　　為了方便測(cè)試，官方還提供了一個(gè)例子。請(qǐng)下載：

　　https://www.showdoc.cc/script/api_demo.test

　　下載后，把a(bǔ)pi_demo.test文件放在showdoc_api.sh所在的目錄或者子目錄下。運(yùn)行的時(shí)候它便會(huì)生成文檔到你指定的項(xiàng)目地址中。

　　如果你想?yún)⒖脊俜絛emo是怎么寫(xiě)的，可用鼠標(biāo)右擊api_demo.test，選擇編輯。仿照此種寫(xiě)法，在你的項(xiàng)目中插入類似的注釋，也能達(dá)到自動(dòng)生成文檔的效果。詳細(xì)語(yǔ)法會(huì)在文章后面部分說(shuō)明。

　　如果你想應(yīng)用到其他項(xiàng)目，可以把showdoc_api.sh復(fù)制一份到其他項(xiàng)目中。使用方法和前面一樣。

更新日志

　　2018年11月

　　增加快速?gòu)?fù)制分享鏈接的功能

　　為了加強(qiáng)多人多團(tuán)隊(duì)情形下的項(xiàng)目協(xié)作，正式推出團(tuán)隊(duì)管理功能

　　2018年10月

　　為了應(yīng)對(duì)復(fù)雜項(xiàng)目?jī)?nèi)容的分類需求，showdoc在原來(lái)目錄支持的基礎(chǔ)上增加一層子目錄，支持到了三級(jí)目錄。用戶在新建目錄的時(shí)候選擇父層目錄為二級(jí)目錄即可。