shoDoc自动生成API文档使用说明

冷不防 2021-07-26 23:40 603阅读 0赞

# shoDoc使用说明 #

*  操作系统windos,其他操作系统见官网介绍

### 自动生成API ###

主要步骤：

1.  安装git for windows :[git][] （已安装可跳过此步骤）
2.  下载官方脚本showdoc\_api.sh：[showDoc脚本][showDoc]
3.  将脚本showdoc\_api.sh拷贝到项目的根目录，如图。  
    ![format_png][]
4.  打开脚本showdoc\_api.sh配置相关参数：api\_key,api\_token和url  
    ![format_png 1][]  
    这里我使用的是使用www.showdoc.cc ，则不需要修改。如果是使用开源版showdoc，则需要将地址改为http://xx.com/server/index.php?s=/api/open/fromComments ，其中，别忘记了url里含server目录。
5.  api\_key和api\_token的获取：新建一个showDoc项目，点击项目目录上的设置图标。进入如下页面，通过开发api获取到api\_key和api\_token  
    ![format_png 2][]  
    将api\_key 和api\_token配置到脚本showdoc\_api.sh中。
6.  在需要生成api文档的地方添加如下注释：  
    ![format_png 3][]  
    7.回到项目目录，在文件夹中双击运行脚本showdoc\_api.sh，等待检索完毕即可自动生成api文档。  
    ![format_png 4][]
7.  登录showDoc查看文档生成结果，大致如下图，下图是官方demo生成的文档。  
    ![format_png 5][]

###### 注释结构的自定义代码块。将如下代码拷贝到VSCode或者HBuidex的自定义代码块–自定义JS代码块中即可通过showdoc快捷生成注释模板。 ######

Hbuiderx使用tab可快速切换到下一个输入位置，但是输入中文会导致tab位置丢失，特别注意

"showDoc":{ 
    			"prefix":"showdoc",
    			"body":[
    			"/**",
    			"* showdoc",
    			"* @catalog $1",
    			"* @title $2",
    			"* @description $3",
    			"* @method ${4:GET/POST}",
    			"* @url https:\/\/www.showdoc.cc/home/user/login ",
    			"* @param $5 ${6:Y/N} ${7:string/num/object/boolean/array} $8 ",
    			"* @param $9 ${10:Y/N} ${11:string/num/object/boolean/array} $12 " ,
    			"* @param $13 ${14:Y/N} ${15:string/num/object/boolean/array} $16" , 
    			"* @return {'Msg':'ok','Data':{'uid':'1','username':'12154545','name':'吴系挂'}}" ,
    			"* @return_param $17 ${18:string/num/object/boolean/array} $19 ",
    			"* @return_param $29 ${21:string/num/object/boolean/array} $22",
    			"* @remark $23",
    			"* @number 99",
    			"*/$0"
    			],
    			"triggerAssist": false,
    			"description": "showDocAPI文档自动生成"
    	}

### 自定义脚本生成文档 ###

参见：[https://www.showdoc.cc/page/102098][https_www.showdoc.cc_page_102098]  
核心思想:编辑自动脚本，提取文档内容,假设文档内容存储为content。  
调用官方的api:

**请求URL：**  
如果你使用www.showdoc.cc ,则请求URL为

https://www.showdoc.cc/server/api/item/updateByApi

如果你使用开源版的showdoc ,则请求url为

http://xx.com/server/index.php?s=/api/item/updateByApi

**请求方式：**

*  POST

**参数：**

<table> 
 <thead> 
  <tr> 
   <th align="left">参数名</th> 
   <th align="left">必选</th> 
   <th align="left">类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">api_key</td> 
   <td align="left">是</td> 
   <td align="left">string</td> 
   <td>项目的api_key,获取方法同上</td> 
  </tr> 
  <tr> 
   <td align="left">api_token</td> 
   <td align="left">是</td> 
   <td align="left">string</td> 
   <td>项目的api_token,获取方法同上</td> 
  </tr> 
  <tr> 
   <td align="left">cat_name</td> 
   <td align="left">否</td> 
   <td align="left">string</td> 
   <td>可选参数。当页面文档处于目录下时，请传递目录名。当目录名不存在时，showdoc会自动创建此目录。需要创建多层目录的时候请用斜杆隔开，例如 “一层/二层/三层”</td> 
  </tr> 
  <tr> 
   <td align="left">page_title</td> 
   <td align="left">是</td> 
   <td align="left">string</td> 
   <td>页面标题。请保证其唯一。（或者，当页面处于目录下时，请保证页面标题在该目录下唯一）。当页面标题不存在时，showdoc将会创建此页面。当页面标题存在时，将用page_content更新其内容</td> 
  </tr> 
  <tr> 
   <td align="left">page_content</td> 
   <td align="left">是</td> 
   <td align="left">string</td> 
   <td>页面内容，可传递markdown格式的文本或者html源码</td> 
  </tr> 
  <tr> 
   <td align="left">s_number</td> 
   <td align="left">否</td> 
   <td align="left">number</td> 
   <td>可选，页面序号。默认是99。数字越小，该页面越靠前</td> 
  </tr> 
 </tbody> 
</table>

*  成功时的返回示例

{  
         "error_code" : "0", 
         "data" : {  
              "page_id" : "101921", 
              "author_uid" : "0", 
              "author_username" : "from_api", 
              "item_id" : "12011", 
              "cat_id" : "25619", 
              "page_title" : "api测试", 
              "page_comments" : "", 
              "page_content" : "我是测试内容555455666666666", 
              "s_number" : "99", 
              "addtime" : "1484444430" 
         } 
     }

*  认证失败时的返回示例

{  
         "error_code" : "10306", 
         "error_message" : "api_key 或 api_token 不匹配" 
     }

[git]: https://git-scm.com/download/win
[showDoc]: https://www.showdoc.cc/script/showdoc_api.sh
[format_png]: /images/20210726/7feaaaf8647e4522b5b414305aa2c83b.png
[format_png 1]: /images/20210726/6c1508be8ac54632a04df2fd5d114159.png
[format_png 2]: /images/20210726/cfdfe62942e04b198e206fc856dc23fc.png
[format_png 3]: /images/20210726/573ae9701bb643cfbad86c46ea4bf447.png
[format_png 4]: /images/20210726/5975e3774d0e4918a05fd8d76f7a3e0b.png
[format_png 5]: /images/20210726/d34046be6d9440d5a9be5f634282e13b.png
[https_www.showdoc.cc_page_102098]: https://www.showdoc.cc/page/102098