这个在线文档工具, 让我上头了!

showdoc + runapi

最近, 一个朋友推荐了我一个在线的项目文档工具showDoc和RunApi. 出于对他人的尊重, 我特地使用了一下, 不用不知道, 一用就"上头了", 借这个上头劲赶紧把文章给撸出来. 好让更多的人看到

RunApi和showdoc相辅相成：showdoc以文档为核心，侧重文档编写和知识资料沉淀。而runapi则以接口为核心，包含接口测试、管理等一系列功能。同时它将自动生成文档到showdoc，以及共用showdoc的团队管理机制，很好地实现接口的自动化和多人协作。相信使用 showdoc + runapi 这两个工具组合，能够极大地提高IT团队的效率。

ShowDoc

工具介绍

官网入口

我们看他这个官网, 这个官网就很讲究, 绿色, 要想生活过得去, 我们总要见点绿… 不开玩笑了. 我们可以从官网的醒目介绍中可以看到这是一个非常适合IT团队的在线API文档、技术文档工具

在这里插入图片描述

经过我的使用后发现, 这个确实好用. 稍微介绍下:

• 对于每种类型的文档(api, 数据字典, 团队技术文档等)都会有模板供你使用. 如果你的文档极具个人风格, 还可以支持自定义模板.
• 在这些文档编写完成后, 我们可以通过url直接访问, 也可以将其导出成word或者Markdown文档, 还可以添加团队成员,团队内成员共享. 甚至可以转让文档, 让你的离职交接更加效率(溜得更快~~~)
• 支持自动生成接口文档功能

使用指南

注册

话不多说,开始使用 点此进行注册 邀请码:9aa8d536 (动动小手填写下吧. 谢谢大家了)

在这里插入图片描述

按要求注册即可

在这里插入图片描述

ps: 需要注意的是, 在注册成功后, 系统会发送一条激活链接, 需要我们进入邮箱点击该链接. 点击后我们便可以正常使用了(如果不点击的话, 每次返回首页会有弹窗提示, 强迫症表示忍不住)

项目文档操作

1. 创建项目

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

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

在这里插入图片描述

1. 在新建项目下填入相关信息 ps: 项目创建方式有四种:
   • 直接创建
   • 复制之前的项目创建
   • 通过导入的文件进行创建
   • 通过脚本和注解自动生成创建(有点类似swagger)

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

在这里插入图片描述

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

在这里插入图片描述

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

在这里插入图片描述

2. 创建项目文档

1. 进入后, 我们通过右侧工具栏进行文档的创建, 我们首先创建一个接口文档
   • 我们可以看到这是一个MarkDown编辑器, 类似咱们C站哈.
   • 在输入标题后, 我们可以直接去编辑我们想要的模板类型, 也可以直接使用之前的模板, 还可以将自己写好文档的制作成模板哦

在这里插入图片描述

1. 在这里演示使用模板创建接口文档,

在这里插入图片描述

在保存之后返回, 我们可以进入这个项目的主页了, 默认展示第一个文档中的内容

3. 分享项目文档

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

1. 点击右侧工具栏分享

在这里插入图片描述

1. 分享页面复制url https://www.showdoc.com.cn/timepause?page_id=5770777030238667 访问密码: 123456

在这里插入图片描述

4. 导出项目文档

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

1. 我们仍可通过右侧工具栏对文档进行编辑, 下面我们点击导出

在这里插入图片描述

1. 选择导出格式

在这里插入图片描述

1. 打开导出的文档

在这里插入图片描述

5. 为项目文档添加成员

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

下面演示如何添加成员

1. 点击项目的编辑选项

在这里插入图片描述

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

在这里插入图片描述

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

在这里插入图片描述

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

在这里插入图片描述

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

在这里插入图片描述

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

在这里插入图片描述

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

在这里插入图片描述

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. 点击文档链接后生成文档链接

在这里插入图片描述

1. 在线访问接口的测试文档 https://www.showdoc.cc/1132882563363840?page_id=5772373077012728 访问密码: 874803835

在这里插入图片描述

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