介绍

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文档。


  1. chmod +x showdoc_api.sh
  2. ./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/

语法说明

一个标准语法例子:


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

语法说明

  1. @catalog // 生成文档要放到哪个目录。如果只是二级目录,则直接写目录名字。如果是三级目录,而需要写二级目录/三级目录,即用 / 隔开。
  2. @title //表示生成的文档标题
  3. @description // 是文档内容中对接口的描述信息
  4. @method //接口请求方式。一般是get或者post
  5. @url //接口URL
  6. @param //参数表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。
  7. @return //返回内容。请把返回内容压缩在同一行内。如果是json,程序会自动进行格式化展示。 如果是非json内容,则原样展示。
  8. @return_param //返回参数的表格说明。一行注释对应着表格的一行。用空格或者tab符号来隔开每一列信息。
  9. @remark //备注信息
  10. @number //可选。文档的序号。

其他信息

请严格按照我们的语法来填写程序注释。如果格式不对,则可能引发未知的解析错误。

出于数据安全考虑,showdoc不允许直接通过代码删除文档。只能新增或者修改。所以,如果你要删除文档,请登录showdoc网页端完成。

本脚本只能通过特定的程序注释来生成文档,使用范围有限。如果你是想通过其他方式自由地生成文档,如通过word、通过博客软件等,请参考我们更自由的开放API:https://www.showdoc.cc/page/1...

如果你的项目下太多文件,则可能导致脚本扫描很慢。推荐把脚本放到需要生成注释的那个目录里。一般来讲,一个项目不会所有目录都需要生成文档的

原文地址:https://segmentfault.com/a/1190000016070247

如何利用showdoc自动生成API文档的更多相关文章

  1. 利用ShowDoc自动生成api接口文档

    最近在做新项目,感觉写完一个接口 还要去再写一遍api文档 挺浪费时间的,所以借用ShowDoc的api开放功能 自动生成api文档. 首先 去 https://www.showdoc.cc/ 注册一 ...

  2. Asp.Net Core 轻松学-利用 Swagger 自动生成接口文档

    前言     目前市场上主流的开发模式,几乎清一色的前后端分离方式,作为服务端开发人员,我们有义务提供给各个客户端良好的开发文档,以方便对接,减少沟通时间,提高开发效率:对于开发人员来说,编写接口文档 ...

  3. Spring Boot 项目学习 (四) Spring Boot整合Swagger2自动生成API文档

    0 引言 在做服务端开发的时候,难免会涉及到API 接口文档的编写,可以经历过手写API 文档的过程,就会发现,一个自动生成API文档可以提高多少的效率. 以下列举几个手写API 文档的痛点: 文档需 ...

  4. Asp.Net Core 轻松学系列-5利用 Swagger 自动生成接口文档

    目录 前言 结语 源码下载 前言     目前市场上主流的开发模式,几乎清一色的前后端分离方式,作为服务端开发人员,我们有义务提供给各个客户端良好的开发文档,以方便对接,减少沟通时间,提高开发效率:对 ...

  5. 使用bee自动生成api文档

    beego中的bee工具可以方便的自动生成api文档,基于数据库字段,自动生成golang版基于beego的crud代码,方法如下: 1.进入到gopath目录的src下执行命令: bee api a ...

  6. 自动生成api文档

    vs2010代码注释自动生成api文档 最近做了一些接口,提供其他人调用,要写个api文档,可是我想代码注释已经写了说明,能不能直接把代码注释生成api?于是找到以下方法 环境:vs2010 先下载安 ...

  7. 试试使用 eolinker 扫描 GitLab 代码注释自动生成 API 文档?

    前言: 一般写完代码之后,还要将各类参数注解写入API文档,方便后续进行对接和测试,这个过程通常都很麻烦,如果有工具可以读取代码注释直接生成API文档的话,那会十分方便. 此前一直都是在使用eolin ...

  8. SpringBoot结合Swagger2自动生成api文档

    首先在pom.xml中添加如下依赖,其它web,lombok等依赖自行添加 <dependency> <groupId>io.springfox</groupId> ...

  9. go实践之swagger自动生成api文档

    文章目录 go实践之swagger自动生成api文档 1.安装需要用到的包 2.接口代码支持swagger 3. 生成swagger接口 go实践之swagger自动生成api文档 作为一个后端开发, ...

随机推荐

  1. How to: Set Properties of Web Application Projects

    https://msdn.microsoft.com/library/aa983454(v=vs.100).aspx ASP.NET Web application projects share th ...

  2. Kaggle "Microsoft Malware Classification Challenge"——就是沙箱恶意文件识别,有 Opcode n-gram特征 ASM文件图像纹理特征 还有基于图聚类方法

    使用图聚类方法:Malware Classification using Graph Clustering 见 https://github.com/rahulp0491/Malware-Classi ...

  3. go语言笔记——多值函数,本质上和nodejs的回调很像,不过nodejs是回调的第一个参数是err,而golang里是第二个!

    5.2 测试多返回值函数的错误 Go 语言的函数经常使用两个返回值来表示执行是否成功:返回某个值以及 true 表示成功:返回零值(或 nil)和 false 表示失败(第 4.4 节).当不使用 t ...

  4. Ned的难题

    题目描述 Ned再也看不下去Robert的种种恶习,于是他决定出一道题来让他醒悟. Ned的题目是这样: 给出一个有n个数的序列,求其中所有连续子序列的数的最大公因数的乘积模1000000009的值. ...

  5. bzoj3011

    可并堆 复习一下可并堆 维护一个大跟堆,每次把节点儿子打上边权标记,然后合并,可并堆上维护一个size,每次把大于l的弹出,size就是答案 程序中那个d写l和r速度差不多,我写l是表示右儿子到u的最 ...

  6. html5中不再支持的元素

    html5中不再支持的元素:1.acronym(建议abbr) : 定义首字母缩写2.applet(建议object): 定义 applet3.basefont(使用css控制)4.big(使用css ...

  7. 【洛谷4770/UOJ395】[NOI2018]你的名字(后缀数组_线段树合并)

    题目: 洛谷4770 UOJ395 分析: 一个很好的SAM应用题-- 一句话题意:给定一个字符串\(S\).每次询问给定字符串\(T\)和两个整数\(l\).\(r\),求\(T\)有多少个本质不同 ...

  8. android GPS 定位,取位置信息

    现在很多app ,需要取位置信息,所以我也做了一个模块用来取位置信息:   加入位置服务所需的权限: <uses-permission android:name="android.pe ...

  9. excel另存为csv

    # -*- coding: utf-8 -*- """ Created on Tue Jul 11 21:25:57 2017 import pandas as pd i ...

  10. [转]linux grep命令

    转自:http://www.cnblogs.com/end/archive/2012/02/21/2360965.html 1.作用Linux系统中grep命令是一种强大的文本搜索工具,它能使用正则表 ...