怎样应用showdoc自动天生API文档

2023年12月18日 283次阅读 来源: star7th

引见

showdoc是一个合适IT团队的文档东西，浏览本文前须要对showdoc有基本相识 。基本引见可看：https://www.showdoc.cc/help

关于写API文档这件事，虽然说文本编辑软件或许接口管理软件能在某种程度上进步我们的效力，但我们依旧能够试图借助手艺的气力，更自动化地天生API文档，开释本身的生产力。
为此，showdoc官方供应了一种自动化解决方案。在代码里编写特定花样的顺序解释，然后showdoc经由过程读取这些解释来自动天生文档。因为这类体式格局不跟特定的言语耦合，因而它的运用范围相称普遍，可用支撑c++、java、php、node、python等等罕见的主流言语。
采纳这类体式格局，只管我们在第一次填写解释的时刻能够会有些烦琐，然则它后期带来的可保护性是异常高的。代码更改后，不须要再分外登录showdoc，直接在代码里修正解释即可。同时自动化的剧本也能够到场延续集成或许某些自动化工程里，让“写API文档”这件事如”单元测试”般归入工程工作流内里。

windows下运用指引

windows没法直接运转sh剧本，须要分外下载软件。
引荐下载git for windows：https://git-scm.com/download/win 下载后直接双击装置即可。
假如从官网下载比较慢，可用斟酌下载由第三方开发者保护的国内版(showdoc官方不保证其历久稳固)：
https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe

以上软件是基本环境。装置好了后，还须要下载showdoc官方剧本：https://www.showdoc.cc/script/showdoc_api.sh
下载后，将showdoc_api.sh放在你的项目目次下。右击，挑选编辑。
剧本内容的前面有两个变量，api_key 和 api_token ，这个须要用户自行填写。关于这两个变量的取值，请登录showdoc，进入某个项目的设置，点击开放API，便能够看到申明。showdoc_api.sh天生的文档会放进你填写的这个项目里。除了api_key 和 api_token ，另有一个url变量。假如是运用www.showdoc.cc ，则不须要修正。假如是运用开源版showdoc，则须要将地点改成http://xx.com/server/?s=/api/open/fromComments 个中，别忘记了url里含server目次。
填写终了，保留。然后直接双击运转，剧本会自动递归扫描本目次和子目次的一切文本代码文件，并天生API文档。
为了轻易测试，官方还供应了一个例子。请下载：
https://www.showdoc.cc/script/api_demo.test
下载后，把api_demo.test文件放在showdoc_api.sh地点的目次或许子目次下。运转的时刻它便会天生文档到你指定的项目地点中。
假如你想参考官方demo是怎样写的，可用鼠标右击api_demo.test，挑选编辑。模仿此种写法，在你的项目中插进去相似的解释，也能到达自动天生文档的结果。细致语法会在文章背面部份申明。

假如你想应用到其他项目，能够把showdoc_api.sh复制一份到其他项目中。运用方法和前面一样。

Linux/Mac下运用指引

先cd进入你的项目目次，敕令行形式下输入：

wget https://www.showdoc.cc/script/showdoc_api.sh

下载终了，编辑

vi showdoc_api.sh

剧本内容的前面有两个变量，api_key 和 api_token ，这个须要用户自行填写。关于这两个变量的取值，请登录showdoc，进入某个项目的设置，点击开放API，便能够看到申明。showdoc_api.sh天生的文档会放进你填写的这个项目里。除了api_key 和 api_token ，另有一个url变量。假如是运用 www.showdoc.cc ，则不须要修正。假如是运用开源版showdoc，则须要将地点改成http://xx.com/server/?s=/api/… ，个中，别忘记了url里含server目次。

保留文件后。实行以下敕令，剧本会自动递归扫描本目次和子目次的一切文本代码文件，并天生API文档。

 chmod +x showdoc_api.sh
./showdoc_api.sh

为了轻易测试，官方还供应了一个例子。请下载：
wget https://www.showdoc.cc/script/api_demo.test

下载后，把api_demo.test文件放在showdoc_api.sh地点的目次或许子目次下。运转的时刻它便会天生文档到你指定的项目地点中。
假如你想参考官方demo是怎样写的，可用vi敕令翻开api_demo.test。模仿此种写法，在你的项目中插进去相似的解释，也能到达自动天生文档的结果。细致语法会在文章背面部份申明。

假如你还想应用到其他项目，能够把showdoc_api.sh复制一份到其他项目中。运用方法和前面一样。
或许不转移位置，直接经由过程参数指定扫描目次。如

./showdoc_api.sh /myapp/demo/

语法申明

一个规范语法例子：

    /**
    * showdoc
    * @catalog 测试文档/用户相干
    * @title 用户登录
    * @description 用户登录的接口
    * @method get
    * @url https://www.showdoc.cc/home/user/login
    * @param username 必选 string 用户名  
    * @param password 必选 string 暗码  
    * @param name 可选 string 用户昵称  
    * @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}
    * @return_param groupid int 用户组id
    * @return_param name string 用户昵称
    * @remark 这里是备注信息
    * @number 99
    */

语法申明


@catalog // 天生文档要放到哪一个目次。假如只是二级目次，则直接写目次名字。假如是三级目次，而须要写二级目次/三级目次，即用 / 离隔。  
@title   //示意天生的文档题目 
@description // 是文档内容中对接口的形貌信息  
@method  //接口要求体式格局。平常是get或许post 
@url  //接口URL  
@param //参数表格申明。一行解释对应着表格的一行。用空格或许tab标记来离隔每一列信息。  
@return  //返回内容。请把返回内容压缩在统一行内。假如是json，顺序会自动举行花样化展现。 假如黑白json内容，则原样展现。
@return_param //返回参数的表格申明。一行解释对应着表格的一行。用空格或许tab标记来离隔每一列信息。
@remark  //备注信息 
@number   //可选。文档的序号。

其他信息

请严厉根据我们的语法来填写顺序解释。假如花样不对，则能够激发未知的剖析毛病。

出于数据平安斟酌，showdoc不允许直接经由过程代码删除文档。只能新增或许修正。所以，假如你要删除文档，请登录showdoc网页端完成。

本剧本只能经由过程特定的顺序解释来天生文档，运用范围有限。假如你是想经由过程其他体式格局自在地天生文档，如经由过程word、经由过程博客软件等，请参考我们更自在的开放API：https://www.showdoc.cc/page/1…

假如你的项面前目今太多文件，则能够致使剧本扫描很慢。引荐把剧本放到须要天生解释的谁人目次里。平常来说，一个项目不会一切目次都须要天生文档的

    原文作者：star7th
    原文地址: https://segmentfault.com/a/1190000016070247
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。
点赞