由于后端與前端使用ajax交互,后端寫(xiě)接口文檔變得非常有必要。以前我習(xí)慣用word寫(xiě)接口文檔,但是最近與同事合作編寫(xiě)后端,word并不適合使用svn工具做同步,因?yàn)閟vn、git等無(wú)法自動(dòng)合并word。所以打算把文檔寫(xiě)成文本的格式。
一開(kāi)始想到的是用markdown
語(yǔ)法來(lái)寫(xiě)。markdown語(yǔ)法大全
但是接口文檔最重要的一個(gè)特性是,接口多,需要給每個(gè)接口標(biāo)序號(hào)(如下圖)。
當(dāng)然markdown支持序號(hào),但是支持得并不完美,比如上下兩個(gè)序號(hào)之間最多只能有一個(gè)空行,并且空行不能寫(xiě)文字,這樣就只能光寫(xiě)接口標(biāo)題了,沒(méi)有空間寫(xiě)接口內(nèi)容了。
請(qǐng)問(wèn)適合寫(xiě)接口文檔的方法是什么?最好就是一種語(yǔ)法,而不是一個(gè)軟件
感謝大家的回答,考慮到markdown
目前的趨勢(shì),還是決定繼續(xù)使用markdown
,現(xiàn)在已經(jīng)想到解決辦法,markdown
只是一種語(yǔ)法,到底怎么顯示,還是由軟件或者瀏覽器插件來(lái)決定的,我找到兩款chrome插件
能自動(dòng)把原文中的標(biāo)題提取出來(lái)生成目錄,并且能給目錄自動(dòng)加序號(hào)(如果原文標(biāo)題本身就有序號(hào),它也會(huì)加自己的序號(hào),所以原文標(biāo)題不能有序號(hào))
同樣能把原文中的標(biāo)題提取出來(lái)生成目錄,但是不會(huì)加序號(hào),對(duì)于不需要序號(hào),或者接口較少的,可以用這個(gè),我更喜歡這個(gè)插件的目錄樣式,可惜功能缺了一點(diǎn)。
這兩款插件其實(shí)是提供給文檔閱讀者的,文檔編輯者倒是可以不需要,全看個(gè)人喜好了,chrome官方市場(chǎng)里就找到這兩款了,不知道國(guó)內(nèi)有沒(méi)有人開(kāi)發(fā)了插件沒(méi)傳到chrome市場(chǎng)
eoLinker接口管理平臺(tái) | 全球領(lǐng)先API接口管理平臺(tái),Google谷歌開(kāi)發(fā)者聯(lián)盟合作項(xiàng)目企業(yè)相當(dāng)不錯(cuò)
APIJSON自動(dòng)化在線(xiàn)解析
完全自動(dòng)生成文檔,自動(dòng)管理測(cè)試用例,不用寫(xiě)任何代碼
http://39.108.143.172/
北大青鳥(niǎo)APTECH成立于1999年。依托北京大學(xué)優(yōu)質(zhì)雄厚的教育資源和背景,秉承“教育改變生活”的發(fā)展理念,致力于培養(yǎng)中國(guó)IT技能型緊缺人才,是大數(shù)據(jù)專(zhuān)業(yè)的國(guó)家
北大青鳥(niǎo)中博軟件學(xué)院創(chuàng)立于2003年,作為華東區(qū)著名互聯(lián)網(wǎng)學(xué)院和江蘇省首批服務(wù)外包人才培訓(xùn)基地,中博成功培育了近30000名軟件工程師走向高薪崗位,合作企業(yè)超4
中公教育集團(tuán)創(chuàng)建于1999年,經(jīng)過(guò)二十年潛心發(fā)展,已由一家北大畢業(yè)生自主創(chuàng)業(yè)的信息技術(shù)與教育服務(wù)機(jī)構(gòu),發(fā)展為教育服務(wù)業(yè)的綜合性企業(yè)集團(tuán),成為集合面授教學(xué)培訓(xùn)、網(wǎng)
達(dá)內(nèi)教育集團(tuán)成立于2002年,是一家由留學(xué)海歸創(chuàng)辦的高端職業(yè)教育培訓(xùn)機(jī)構(gòu),是中國(guó)一站式人才培養(yǎng)平臺(tái)、一站式人才輸送平臺(tái)。2014年4月3日在美國(guó)成功上市,融資1
曾工作于聯(lián)想擔(dān)任系統(tǒng)開(kāi)發(fā)工程師,曾在博彥科技股份有限公司擔(dān)任項(xiàng)目經(jīng)理從事移動(dòng)互聯(lián)網(wǎng)管理及研發(fā)工作,曾創(chuàng)辦藍(lán)懿科技有限責(zé)任公司從事總經(jīng)理職務(wù)負(fù)責(zé)iOS教學(xué)及管理工作。
浪潮集團(tuán)項(xiàng)目經(jīng)理。精通Java與.NET 技術(shù), 熟練的跨平臺(tái)面向?qū)ο箝_(kāi)發(fā)經(jīng)驗(yàn),技術(shù)功底深厚。 授課風(fēng)格 授課風(fēng)格清新自然、條理清晰、主次分明、重點(diǎn)難點(diǎn)突出、引人入勝。
精通HTML5和CSS3;Javascript及主流js庫(kù),具有快速界面開(kāi)發(fā)的能力,對(duì)瀏覽器兼容性、前端性能優(yōu)化等有深入理解。精通網(wǎng)頁(yè)制作和網(wǎng)頁(yè)游戲開(kāi)發(fā)。
具有10 年的Java 企業(yè)應(yīng)用開(kāi)發(fā)經(jīng)驗(yàn)。曾經(jīng)歷任德國(guó)Software AG 技術(shù)顧問(wèn),美國(guó)Dachieve 系統(tǒng)架構(gòu)師,美國(guó)AngelEngineers Inc. 系統(tǒng)架構(gòu)師。