干掉 Postman?测试接口直接生成API文档,这个工具贼好用

简介: 这个工具贼好用
本文案例收录在 https://github.com/chengxy-nds/Springboot-Notebook

大家好,我是小富~

前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下。

ShowDoc一个非常适合团队的在线API文档工具,也支持用docker自建文档服务,不过为了方便演示,我直接用了平台在线服务。官网地址:

https://www.showdoc.com.cn/item/index

可以使用markdown语法来写API文档、数据字典文档、技术文档、在线excel文档。但像我这种资深的懒人程序员,其实更看重的是showdoc的自动化生成文档的特性,它可以从代码注释中自动生成API文档,或者搭配RunApi客户端(类似postman的api调试工具)一边调试接口、一边自动生成文档。

下边从头演示下,来瞅瞅这玩意好用在哪?

主页

初识 ShowDoc

ShowDoc新建项目可选常规的API文档、在线表格、或者单页文档(不支持目录分层),允许对项目文档设置访问密码,自定义域名,这里并不是真正意义上的“域名”,只是在文档服务域名后加了一级目录,例如:

www.showdoc.com.cn/程序员内点事

可以复制现有的项目,或直接导入Postmanswagger的API接口配置Json文件。提供的开放API是自动化生成文档的关键,先记住有api_keyapi_token这两个属性,后边详细讲。

进入项目后点击右上角 + 编辑文档,ShowDoc预置了几种文档模板,也可以把自定义的文档存为模板;支持在线Mock服务,提前定义好接口的数据格式,先提供在线临时接口,这样就可以和前端同步开发,后边无缝切换;还有个简单的API在线测试功能。

在线表格样式很简洁

导出文档有wordMarkdown两种格式。

支持版本控制,能看到每次修改的记录,回滚任意一个版本的修改。

在向别人分享在线文档时,如果不想将整个API目录都暴漏,可以选择进行单页面分享。

看到这感觉showdoc很普通啊,好像没什么特别的地方,上边的这些文档都是需要我们手动书写的,比较繁琐不推荐这么搞,接下来咱们看看如何自动化生成文档。

自动生成文档

showdoc有三种自动生成API文档的方式:

  • 使用Runapi工具自动生成(推荐
  • 使用程序代码注释自动生成
  • 自动生成数据字典
  • 自己写程序调用接口来生成

Runapi工具

Runapi是一个以接口为核心的开发测试工具(可以看做是Postman的精简版)。目前客户端支持winmaclinux平台和在线版 ,包含接口测试、自动流程测试、Mock数据、项目协作等功能。

单纯的RunapiPostman相比优势并不大,而与showdoc配合使用效率比较显著,用runapi测试接口的同时它将自动生成API文档到showdoc,也可共用showdoc的团队管理机制实现多人协作。

Runapi客户端可以创建带调试的API接口文档、或者Markdown格式的文档。

比如我们新建个项目“程序员内点事”,分别建三个接口“点在”、“在看”、“关注”,紧接着快速生成参数和响应结果数据并保存。

点击右上角的文档链接设置访问密码,不填默认是公开的,复制文档链接在浏览器中打开,看到API接口文档已经生成。runapi还有全局参数、环境隔离。其实Postman也支持这样的功能,不过毕竟不是国内产品,网络访问等方面很受限制。

还有一个比较好的地方,Runapi支持接口执行前后的脚本,比如响应数据的断言测试,弹框显示都挺好用的。

代码注释

把接口的信息写在注释里也可以自动生成文档到showdoc,但这种我并不太喜欢,主要是侵入性比较强,让代码的阅读性变的比较差,一坨坨看着很不爽。

    /**
    * showdoc
    * @catalog 测试文档/用户相关
    * @title 用户注册
    * @description 用户注册的接口
    * @method post
    * @url https://www.showdoc.com.cn/home/user/login
    * @param username 必选 string 用户名  
    * @param password 必选 string 密码  
    * @param name 可选 string 用户昵称  
    * @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}
    * @return_param groupid int 用户组id
    * @return_param name string 用户昵称
    * @remark 这里是备注信息
    * @number 99
    */
    public Object register(){

这种方式的实现也比较简单,还记得前边的提到的api_keyapi_token这两个属性嘛,现在派上用场了,下边我用windows环境演示。

首先本地要有git环境:

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_keyapi_token变量值,URL如果没搭建自己的文档服务不用改。

showdoc_api.sh放在你的项目目录下,直接双击运行,脚本会自动递归扫描本目录和子目录的所有文本代码文件,并生成API文档。

showdoc_api.sh生成的文档会放进你填写api_token的这个项目里。

生成数据字典

如果我们想直接从数据库字典表生成数据字典文档,showdoc也是支持的,先下载官方提供的脚本

wget https://www.showdoc.cc/script/showdoc_db.sh

修改脚本里的配置,数据库、api_keyapi_token等信息,直接执行后数据库表结构信息同步到showdoc


如下配置的变量名和解释

效果就是如下图这样,生成了数据表字典文档,在一些特定场景下还是很方便的。

开放API

showdoc开放了文档编辑的API,我们可以在代码中调用API创建、编辑文档。这样使用的场景就比较灵活了。

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

API参数如下,文档内容,可传递markdown格式的文本或者html源码都可以。

测试一下接口组装必要的参数,用简易在线API调试工具发送

{
  "api_key": "8e52cbad736aa9832b92acc4b34a830e961861279",
  "api_token": "9dcd8333afa7cde63bf84f8f0db5d2b2116079256",
  "page_title": "xiaofu",
  "page_content": "nihao"
}


看到在showdoc对应的项目里已经创建了名字为xiaofu的文档。

说两句

前边说过showdoc现有的功能postman基本都支持,但postman功能过于繁杂不够简洁,加上网络条件等诸多限制,协同办公的效率并不高,而Runapi配合showdoc在某些场景下能够很大程度上提升我们开发交付的效率,所以能自动生成的绝对不手写!

再怎么BB吹嘘都是苍白的,好不好用,适不适合自己,动手搞一下一目了然

我是小富,下期见~

整理了几百本各类技术电子书,有需要的同学自取。技术群快满了,想进的同学可以加我好友,和大佬们一起吹吹技术。

电子书地址

相关文章
|
1月前
|
API 数据库 决策智能
基于百炼平台qwen-max的api 打造一套 检索增强 图谱增强 智能工具调用决策的智能体
本文介绍了一种基于阿里云百炼平台的`qwen-max` API构建的智能体方案,该方案集成了检索增强、图谱增强及智能工具调用决策三大模块,旨在通过结合外部数据源、知识图谱和自动化决策提高智能回答的准确性和丰富度。通过具体代码示例展示了如何实现这些功能,最终形成一个能灵活应对多种查询需求的智能系统。
158 11
|
1月前
|
自然语言处理 NoSQL API
基于百炼平台qwen-max的api 打造一套 检索增强 图谱增强 基于指令的智能工具调用决策 智能体
基于百炼平台的 `qwen-max` API,设计了一套融合检索增强、图谱增强及指令驱动的智能工具调用决策系统。该系统通过解析用户指令,智能选择调用检索、图谱推理或模型生成等工具,以提高问题回答的准确性和丰富性。系统设计包括指令解析、工具调用决策、检索增强、图谱增强等模块,旨在通过多种技术手段综合提升智能体的能力。
164 5
|
1月前
|
Java 测试技术 数据安全/隐私保护
软件测试中的自动化策略与工具应用
在软件开发的快速迭代中,自动化测试以其高效、稳定的特点成为了质量保证的重要手段。本文将深入探讨自动化测试的核心概念、常见工具的应用,以及如何设计有效的自动化测试策略,旨在为读者提供一套完整的自动化测试解决方案,帮助团队提升测试效率和软件质量。
|
6天前
|
人工智能 前端开发 API
Gemini Coder:基于 Google Gemini API 的开源 Web 应用生成工具,支持实时编辑和预览
Gemini Coder 是一款基于 Google Gemini API 的 AI 应用生成工具,支持通过文本描述快速生成代码,并提供实时代码编辑和预览功能,简化开发流程。
75 38
Gemini Coder:基于 Google Gemini API 的开源 Web 应用生成工具,支持实时编辑和预览
|
1月前
|
Web App开发 IDE 测试技术
Selenium:强大的 Web 自动化测试工具
Selenium 是一款强大的 Web 自动化测试工具,包括 Selenium IDE、WebDriver 和 Grid 三大组件,支持多种编程语言和跨平台操作。它能有效提高测试效率,解决跨浏览器兼容性问题,进行性能测试和数据驱动测试,尽管存在学习曲线较陡、不稳定等缺点,但其优势明显,是自动化测试领域的首选工具。
189 17
Selenium:强大的 Web 自动化测试工具
|
2月前
|
机器学习/深度学习 人工智能 算法
BALROG:基准测试工具,用于评估 LLMs 和 VLMs 在复杂动态环境中的推理能力
BALROG 是一款用于评估大型语言模型(LLMs)和视觉语言模型(VLMs)在复杂动态环境中推理能力的基准测试工具。它通过一系列挑战性的游戏环境,如 NetHack,测试模型的规划、空间推理和探索能力。BALROG 提供了一个开放且细粒度的评估框架,推动了自主代理研究的进展。
53 3
BALROG:基准测试工具,用于评估 LLMs 和 VLMs 在复杂动态环境中的推理能力
|
26天前
|
测试技术 API 数据库
淘宝商品详情高级版 (item_get_pro)API如何测试
要测试淘宝商品详情高级版API(item_get_pro),需先阅读API文档,注册开放平台账号,创建应用获取密钥,搭建测试环境,选择测试工具。测试时设计用例,配置工具,发送请求,验证响应,记录日志。注意安全和数据格式。
|
1月前
|
监控 数据管理 测试技术
API接口自动化测试深度解析与最佳实践指南
本文详细介绍了API接口自动化测试的重要性、核心概念及实施步骤,强调了从明确测试目标、选择合适工具、编写高质量测试用例到构建稳定测试环境、执行自动化测试、分析测试结果、回归测试及集成CI/CD流程的全过程,旨在为开发者提供一套全面的技术指南,确保API的高质量与稳定性。
|
2月前
|
Java 测试技术 API
详解Swagger:Spring Boot中的API文档生成与测试工具
详解Swagger:Spring Boot中的API文档生成与测试工具
62 4
|
2月前
|
监控 测试技术 开发工具
移动端性能测试工具
移动端性能测试工具
64 2