showdoc + 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. 创建项目

创建项目的目的是用于通过项目名来管理项目的相关文档

1. 在主页中选择新建项目
   

2. 在新建项目下填入相关信息

   ps: 项目创建方式有四种:

   • 直接创建
   • 复制之前的项目创建
   • 通过导入的文件进行创建
   • 通过脚本和注解自动生成创建(有点类似swagger)

   这里就使用直接创建, 创建常规的项目, 后续有机会会演示其他的方式
   在三个输入框, 第一个输入项目名, 第二个输入项目描述, 第三个输入项目域名.
   然后设置成公开项目让我们可以通过公网链接来访问. 设置成私有项目则是在原来基础上面对访问密码(123456)

   

3. 提交之后, 我们就可以在主页找到我们的项目了
   

4. 我们可以通过右侧工具栏对项目中的文档进行操作
   

2. 创建项目文档

1. 进入后, 我们通过右侧工具栏进行文档的创建, 我们首先创建一个接口文档

   • 我们可以看到这是一个MarkDown编辑器, 类似咱们C站哈.
   • 在输入标题后, 我们可以直接去编辑我们想要的模板类型, 也可以直接使用之前的模板, 还可以将自己写好文档的制作成模板哦

   

2. 在这里演示使用模板创建接口文档,
   
   在保存之后返回, 我们可以进入这个项目的主页了, 默认展示第一个文档中的内容

3. 分享项目文档

通过url来分享项目. 需要注意的是如果是私有项目需要输入访问密码
适合分享给哪些不想注册但是想看到在线文档的人(比如分享给项目对接时, 需要对接的对象)

1. 点击右侧工具栏分享
   

2. 分享页面复制url

   https://www.showdoc.com.cn/timepause?page_id=5770777030238667
   访问密码: 123456

   

4. 导出项目文档

• 支持导出成word和MarkDown类型
• 导出后的文件名以项目名.doc
• 导出多个接口文档时则会合并成一个文件

1. 我们仍可通过右侧工具栏对文档进行编辑, 下面我们点击导出
   
2. 选择导出格式
   
3. 打开导出的文档
   

5. 为项目文档添加成员

被添加的成员可以直接拥有该项目的使用权

下面演示如何添加成员

1. 点击项目的编辑选项

2. 在成员&团队栏选择添加成员选项

3. 设置项目的相关权限

   • 这里需要注意的是第一个输入框输入的用户名称(申请账号时的邮箱)
   • 还可以设置项目只读or可操作以及哪些目录可见

   

4. 添加完成后, 我们可以看到相关成员的信息

   我们还可以通过添加团队的操作, 通过一个团队指定多个用户, 方便后续在创建其他项目时,项目添加成员的操作

   

5. 切换到成员账号, 可以看到项目已经出现在改成员的主页中了
   

6. 进入该文档, 修改相关文档名称
   

7. 切换到文档创建者的账号, 查看修改是否会同步
   只有点击保存后文档才能同步哦
   

6. 项目文档转让

为了测试转让, 我们首先需要将上步操作添加的成员删除

1. 在高级设置中, 点击转让, 输入接受者的用户名以及自己的登录密码

2. 转让成功后, 会自动跳转到个人主页, 可以看到项目已经过继到另一个人手里了(非常适合离职时的文档交接, 让你溜的更快~)

7. 项目文档归档

需要注意的是文章归档之后便不可访问, 只能复制到新的项目才能够编辑

RunApi介绍

介绍

runapi是一个以接口为核心的开发测试工具，目前有客户端版(推荐，支持win和mac平台）和在线精简版 ，包含接口测试/项目协作等功能，功能上类似一个简化版的postman。点击进入下载页面

使用指南

runapi的调试数据会自动生成markdown文档到showdoc，无须你再额外写文档。但markdown数据很难再逆转回来runapi。所以showdoc原有的历史项目无法直接导入runapi。只是它们可以共用文档浏览、账号体系、团队协作等功能。希望这两个工具互相配合使用能带来效率的提升。

提前准备

1. 创建一个可以有响应的项目

在springboot官网 https://start.spring.io/ ,快速创建springboot项目
别忘记添加web启动器(下图红色部分!)

2. 添加过后导入到自己的idea或者eclipse中
3. 修改启动类

主要是添加了一个@RestController和一个访问方法test1
令我们访问接口方法的时候, 便可以有返回值

@SpringBootApplication
@RestController
public class TestoneApplication {

	public static void main(String[] args) {
		SpringApplication.run(TestoneApplication.class, args);
	}


	@RequestMapping("/test/{name}")
	public String test1(@PathVariable String name){

		return name+"登录成功";
	}
}

开始使用

1. 创建测试项目

创建后可以对项目进行编辑和分享等操作, 这里我们使用默认创建的项目

2. 进行接口调试

需要注意的是第一个两个输入框书写的分别是接口标题和接口描述
在保存之前需要我们进行第3步, 设置返回的接口实例

3. 设置返回实例

这里写成什么样, 接口文档的返回实例就显示成什么样, 内容可从接口文档中复制

4. 点击文档链接后生成文档链接

5. 在线访问接口的测试文档

   https://www.showdoc.cc/1132882563363840?page_id=5772373077012728
   访问密码: 874803835

   

如果觉得还不错的话, 就动动小手点点赞吧! 后续如果有问题的话, 我会继续更新哦~