showdoc + runapi —— 接口文档模板生成管理和接口调试工具
showdoc+runapiShowDoc工具介绍使用指南注册项目文档操作1.创建项目2.创建项目文档3.分享项目文档4.导出项目文档5.为项目文档添加成员6.项目文档转让7.项目文档归档RunApi介绍介绍使用指南提前准备开始使用最近,一个朋友推荐了我一个在线的项目文档工具showDoc和RunApi.出于对他人的尊重,我特地使用了一下,不用不知道,一用就"上头了",借这个上头劲赶紧把文章给撸出来.好让更多的人看到
RunApi和showdoc(https://www.showdoc.com.cn/help)相辅相成：showdoc以文档为核心，侧重文档编写和知识资料沉淀。而runapi则以接口为核心，包含接口测试、管理等一系列功能。同时它将自动生成文档到showdoc，以及共用showdoc的团队管理机制，很好地实现接口的自动化和多人协作。相信使用showdoc+runapi这两个工具组合，能够极大地提高IT团队的效率。
ShowDoc工具介绍官网入口
我们看他这个官网,这个官网就很讲究,绿色,要想生活过得去,我们总要见点绿…不开玩笑了.我们可以从官网的醒目介绍中可以看到这是一个非常适合IT团队的在线API文档、技术文档工具
经过我的使用后发现,这个确实好用.稍微介绍下:
对于每种类型的文档(api,数据字典,团队技术文档等)都会有模板供你使用.如果你的文档极具个人风格,还可以支持自定义模板.
在这些文档编写完成后,我们可以通过url直接访问,也可以将其导出成word或者Markdown文档,还可以添加团队成员,团队内成员共享.甚至可以转让文档,让你的离职交接更加效率(溜得更快~~~)
支持自动生成接口文档功能
使用指南注册话不多说,开始使用点此进行注册邀请码:9aa8d536(动动小手填写下吧.谢谢大家了)
按要求注册即可
ps:需要注意的是,在注册成功后,系统会发送一条激活链接,需要我们进入邮箱点击该链接.点击后我们便可以正常使用了(如果不点击的话,每次返回首页会有弹窗提示,强迫症表示忍不住)
项目文档操作1.创建项目创建项目的目的是用于通过项目名来管理项目的相关文档
在主页中选择新建项目
在新建项目下填入相关信息
ps:项目创建方式有四种:
直接创建复制之前的项目创建通过导入的文件进行创建通过脚本和注解自动生成创建(有点类似swagger)这里就使用直接创建,创建常规的项目,后续有机会会演示其他的方式在三个输入框,第一个输入项目名,第二个输入项目描述,第三个输入项目域名.然后设置成公开项目让我们可以通过公网链接来访问.设置成私有项目则是在原来基础上面对访问密码(123456)
提交之后,我们就可以在主页找到我们的项目了
我们可以通过右侧工具栏对项目中的文档进行操作
2.创建项目文档进入后,我们通过右侧工具栏进行文档的创建,我们首先创建一个接口文档
我们可以看到这是一个MarkDown编辑器,类似咱们C站哈.在输入标题后,我们可以直接去编辑我们想要的模板类型,也可以直接使用之前的模板,还可以将自己写好文档的制作成模板哦在这里演示使用模板创建接口文档,在保存之后返回,我们可以进入这个项目的主页了,默认展示第一个文档中的内容
3.分享项目文档通过url来分享项目.需要注意的是如果是私有项目需要输入访问密码适合分享给哪些不想注册但是想看到在线文档的人(比如分享给项目对接时,需要对接的对象)
点击右侧工具栏分享
分享页面复制url
https://www.showdoc.com.cn/timepause?page_id=5770777030238667访问密码:123456
4.导出项目文档支持导出成word和MarkDown类型导出后的文件名以项目名.doc导出多个接口文档时则会合并成一个文件我们仍可通过右侧工具栏对文档进行编辑,下面我们点击导出选择导出格式打开导出的文档5.为项目文档添加成员被添加的成员可以直接拥有该项目的使用权
下面演示如何添加成员
点击项目的编辑选项2.在成员&团队栏选择添加成员选项
设置项目的相关权限
这里需要注意的是第一个输入框输入的用户名称(申请账号时的邮箱)还可以设置项目只读or可操作以及哪些目录可见添加完成后,我们可以看到相关成员的信息
我们还可以通过添加团队的操作,通过一个团队指定多个用户,方便后续在创建其他项目时,项目添加成员的操作
切换到成员账号,可以看到项目已经出现在改成员的主页中了
进入该文档,修改相关文档名称
切换到文档创建者的账号,查看修改是否会同步只有点击保存后文档才能同步哦
6.项目文档转让为了测试转让,我们首先需要将上步操作添加的成员删除
在高级设置中,点击转让,输入接受者的用户名以及自己的登录密码2.转让成功后,会自动跳转到个人主页,可以看到项目已经过继到另一个人手里了(非常适合离职时的文档交接,让你溜的更快~)
7.项目文档归档需要注意的是文章归档之后便不可访问,只能复制到新的项目才能够编辑
RunApi介绍介绍runapi是一个以接口为核心的开发测试工具，目前有客户端版(推荐，支持win和mac平台）和在线精简版，包含接口测试/项目协作等功能，功能上类似一个简化版的postman。点击进入下载页面
使用指南runapi的调试数据会自动生成markdown文档到showdoc，无须你再额外写文档。但markdown数据很难再逆转回来runapi。所以showdoc原有的历史项目无法直接导入runapi。只是它们可以共用文档浏览、账号体系、团队协作等功能。希望这两个工具互相配合使用能带来效率的提升。
提前准备创建一个可以有响应的项目在springboot官网https://start.spring.io/,快速创建springboot项目别忘记添加web启动器(下图红色部分!)
2.添加过后导入到自己的idea或者eclipse中3.修改启动类
主要是添加了一个@RestController和一个访问方法test1令我们访问接口方法的时候,便可以有返回值
@SpringBootApplication@RestControllerpublicclassTestoneApplication{publicstaticvoidmain(String[]args){SpringApplication.run(TestoneApplication.class,args);}@RequestMapping("/test/{name}")publicStringtest1(@PathVariableStringname){returnname+"登录成功";}}开始使用创建测试项目创建后可以对项目进行编辑和分享等操作,这里我们使用默认创建的项目
2.进行接口调试
需要注意的是第一个两个输入框书写的分别是接口标题和接口描述在保存之前需要我们进行第3步,设置返回的接口实例
3.设置返回实例
这里写成什么样,接口文档的返回实例就显示成什么样,内容可从接口文档中复制
4.点击文档链接后生成文档链接
在线访问接口的测试文档
https://www.showdoc.cc/1132882563363840?page_id=5772373077012728访问密码:874803835
如果觉得还不错的话,就动动小手吧!后续如果有问题的话,我会继续更新哦~
推荐几款接口文档生成神器
gitbook
github地址：https://github.com/GitbookIO/gitbook
开源协议：Apache-2.0License
Star:22.9k
开发语言：javascript
用户：50万+
推荐指数：★★★
示例地址：https://www.servicemesher.com/envoy/intro/arch_overview/dynamic_configuration.html
gitBook是一款文档编辑工具。它的功能类似金山WPS中的word或者微软office中的word的文档编辑工具。它可以用来写文档、建表格、插图片、生成pdf。当然，以上的功能WPS、office可能做得更好，但是，gitBook还有更最强大的功能：它可以用文档建立一个网站，让更多人了解你写的书，另外，最最核心的是，他支持Git，也就意味着，它是一个分布式的文档编辑工具。你可以随时随地来编写你的文档，也可以多人共同编写文档，哪怕多人编写同一页文档，它也能记录每个人的内容，然后告诉你他们之间的区别，也能记录你的每一次改动，你可以查看每一次的书写记录和变化，哪怕你将文档都删除了，它也能找回来！这就是它继承git后的厉害之处！
优点：使用起来非常简单，支持全文搜索，可以跟git完美集成，对代码无任何嵌入性，支持markdown格式的文档编写。
缺点：需要单独维护一个文档项目，如果接口修改了，需要手动去修改这个文档项目，不然可能会出现接口和文档不一致的情况。并且，不支持在线调试功能。
个人建议：如果对外的接口比较少，或者编写之后不会经常变动可以用这个。
smartdoc
gitee地址：https://gitee.com/smart-doc-team/smart-doc
开源协议：Apache-2.0License
Star:758
开发语言：html、javascript
用户：小米、科大讯飞、1加
推荐指数：★★★★
示例地址：https://gitee.com/smart-doc-team/smart-doc/wikis/文档效果图?sort_id=1652819
smart-doc是一个javarestfulapi文档生成工具，smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。smart-doc完全基于接口源码分析来生成接口文档，完全做到零注解侵入，只需要按照java标准注释的写就能得到一个标准的markdown接口文档。
优点：基于接口源码分析生成接口文档，零注解侵入，支持html、pdf、markdown格式的文件导出。
缺点：需要引入额外的jar包，不支持在线调试
个人建议：如果实时生成文档，但是又不想打一些额外的注解，比如：使用swagger时需要打上@Api、@ApiModel等注解，就可以使用这个。
redoc
github地址：https://github.com/Redocly/redoc
开源协议：MITLicense
Star:10.7K
开发语言：typescript、javascript
用户：docker、redocly
推荐指数：★★★☆
示例地址：https://docs.docker.com/engine/api/v1.40/
redoc自己号称是一个最好的在线文档工具。它支持swagger接口数据，提供了多种生成文档的方式，非常容易部署。使用redoc-cli能够将您的文档捆绑到零依赖的HTML文件中，响应式三面板设计，具有菜单/滚动同步。
优点：非常方便生成文档，三面板设计
缺点：不支持中文搜索，分为：普通版本和付费版本，普通版本不支持在线调试。另外UI交互个人感觉不适合国内大多数程序员的操作习惯。
个人建议：如果想快速搭建一个基于swagger的文档，并且不要求在线调试功能，可以使用这个。
knife4j
gitee地址：https://gitee.com/xiaoym/knife4j
开源协议：Apache-2.0License
Star:3k
开发语言：java、javascript
用户：未知
推荐指数：★★★★
示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.html
knife4j是为JavaMVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍。
优点：基于swagger生成实时在线文档，支持在线调试，全局参数、国际化、访问权限控制等，功能非常强大。
缺点：界面有一点点丑，需要依赖额外的jar包
个人建议：如果公司对ui要求不太高，可以使用这个文档生成工具，比较功能还是比较强大的。
yapi
github地址：https://github.com/YMFE/yapi
开源协议：Apache-2.0License
Star:17.8k
开发语言：javascript
用户：腾讯、阿里、百度、京东等大厂
推荐指数：★★★★★
示例地址：http://swagger-bootstrap-ui.xiaominfo.com/doc.html
yapi是去哪儿前端团队自主研发并开源的，主要支持以下功能：
可视化接口管理
数据mock
自动化接口测试
数据导入（包括swagger、har、postman、json、命令行）
权限管理
支持本地化部署
支持插件
支持二次开发
优点：功能非常强大，支持权限管理、在线调试、接口自动化测试、插件开发等，BAT等大厂等在使用，说明功能很好。
缺点：在线调试功能需要安装插件，用户体检稍微有点不好，主要是为了解决跨域问题，可能有安全性问题。不过要解决这个问题，可以自己实现一个插件，应该不难。
个人建议：如果不考虑插件安全的安全性问题，这个在线文档工具还是非常好用的，可以说是一个神器，笔者在这里强烈推荐一下。
apidoc
github地址：https://github.com/apidoc/apidoc
开源协议：MITLicense
Star:8.7k
开发语言：javascript
用户：未知
推荐指数：★★★★☆
示例地址：https://apidocjs.com/example/#api-User
apidoc是一个简单的RESTfulAPI文档生成工具，它从代码注释中提取特定格式的内容生成文档。支持诸如Go、Java、C++、Rust等大部分开发语言，具体可使用apidoclang命令行查看所有的支持列表。
apidoc拥有以下特点：
跨平台，linux、windows、macOS等都支持；
支持语言广泛，即使是不支持，也很方便扩展；
支持多个不同语言的多个项目生成一份文档；
输出模板可自定义；
根据文档生成mock数据；
优点：基于代码注释生成在线文档，对代码的嵌入性比较小，支持多种语言，跨平台，也可自定义模板。支持搜索和在线调试功能。
缺点：需要在注释中增加指定注解，如果代码参数或类型有修改，需要同步修改注解相关内容，有一定的维护工作量。
个人建议：这种在线文档生成工具提供了另外一种思路，swagger是在代码中加注解，而apidoc是在注解中加数据，代码嵌入性更小，推荐使用。
showdoc
github地址：https://github.com/star7th/showdoc
开源协议：ApacheLicence
Star:8.1k
开发语言：javascript、php
用户：超过10000+互联网团队正在使用
推荐指数：★★★★☆
示例地址：https://www.showdoc.com.cn/demo?page_id=9
ShowDoc就是一个非常适合IT团队的在线文档分享工具，它可以加快团队之间沟通的效率。
它都有些什么功能：
响应式网页设计，可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成word文件，以便离线浏览。
权限管理，ShowDoc上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问，而私密项目则需要输入密码验证访问。密码由项目创建者设置。
ShowDoc采用markdown编辑器，点击编辑器上方的按钮可方便地插入API接口模板和数据字典模板。
ShowDoc为页面提供历史版本功能，你可以方便地把页面恢复到之前的版本。
支持文件导入，文件可以是postman的json文件、swagger的json文件、showdoc的markdown压缩包，系统会自动识别文件类型。
优点：支持项目权限管理，多种格式文件导入，全文搜索等功能，使用起来还是非常方便的。并且既支持部署自己的服务器，也支持在线托管两种方式。
缺点：不支持在线调试功能
个人建议：如果不要求在线调试功能，这个在线文档工具值得使用。