最近使用新OpenAPI
接口时发现自带的SwaggerUI
界面不是很友好,一些开源的库,如Knife4j
使用虽然很方便,不过对于比较大的schema
支持不好,容易出现卡顿,目前做的比较好的是ApiFox
,不过不能同步Markdown
文件,而且私有化部署需要另外收费。
其实API
文档服务比较简单,没有太多功能,因此抽空自己开发一个简单的API文档系统
功能介绍
由一个Java
后端和Vue3
前端组成,主要功能如下:
- 从
Swagger
或者OpenAPI
的文档(json/yaml
)文件或URL
路径导入文档系统 - 支持查看
Markdown
文档和API
文档字段等 - 支持新增
Markdown
文档,方便对OpenAPI
文档做一些附加说明等 - 支持分享链接和密码查看,支持分享有效期
- 支持定时从指定
URL
抓取文档数据 - 支持在线调试接口请求
- 支持多级文件夹展示
API
文档
实现技术栈
基于Spring Boot
开发的文档服务器,主要要两个项目:
- 后台服务
simple-api-doc
UI
界面simple-api-doc-ui
(Vue3
)
最后打包的时候合并到一个项目中,成为一个jar
包,最后打包成为一个zip
文件,加压运行即可。
源码:https://github.com/fugary/simple-api-doc
后端框架
Spring Boot
Mybatis
、MybatisPlus
Lombok
Logback
FlywayDB
swagger-parser
前端系统
基于自己对element-plus
的二次封装:https://github.com/fugary/simple-element-plus-template
Vue3
全家桶element-plus
dayjs
lodash-es
monaco-editor
md-editor-v3
编辑Markdown
编辑器markdown-it
安装启动
开源地址:https://github.com/fugary/simple-api-doc
解压启动
找到https://github.com/fugary/simple-api-doc/releases
下载最新版本后解压
进入bin
目录
点击start.bat
启动后可以进入登录页面:http://localhost:9089/
如果要支持MySQL
需要提前配置MySQL
数据库信息。
Docker启动
docker
运行比较简单,只要已经安装好docker
,直接使用命令就可以自动拉去镜像并运行了
docker run -p 9089:9089 fugary/simple-api-doc:latest
常规使用
系统后台管理API
接口,通过分享链接的形式提供给客户
修改密码
启动后进入系统,登录账号admin/12345678
,登录系统后尽快进入【个人资料】修改密码
导入数据
点击【导入数据】,选择需要导入的json
或yaml
文件,或者指定的URL
地址,如果需要认证的话可以根据实际情况去填写信息,支持Basic
和Token
认证方式。
这里以OpanAI的接口为例:
https://raw.githubusercontent.com/openai/openai-openapi/refs/heads/master/openapi.yaml
这个地址不能直接访问,可能需要代理下载下来后使用,或者用代理工具:
导入后可以查看文档详情:
左侧文件夹区域,按照Tag
作为文件夹展示,右侧是主文档区域,可以分享文档,导入数据,调试接口等
文档分享
导入的文档并不是直接对外开放,需要新建一个【文档分享】,通过文档分享链接提供给第三方客户,支持密码和有效期控制
进入【文档分享】页面,点击【新增】按钮,填写分享信息,可以填写名称,以及一些常用配置信息:
新建好之后就有一个分享链接,可以把链接给到第三方使用:
分享查看
复制好分享链接或者直接从分享列表页点击可以跳转到分享页面,分享页面可以【调试接口】,下载Swagger
支持的json
或者yaml
接口文档
右侧是请求体或响应体详细文档信息
接口调试
目前支持简单的接口调试功能,点击【调试接口】,弹出的新窗口可以选择【发送请求】
高级功能
定时导入
定时导入只支持从URL
抓取数据,配置一些定时相关信息即可:
多级文件夹
SwaggerUI
不支持多级文件夹,都是平铺展开,仅用Tag
分组,因此扩展OpenAPI
输出格式添加扩展属性x-simple-folder
,可以支持多级文件夹:
"/get": {
"post": {
"operationId": "get",
"x-simple-folder": "文件夹1/文件夹2"
}
}
注解配置如下:
@Operation(extensions = {
@Extension(properties = {
@ExtensionProperty(name = "x-simple-folder", value = "文件夹1/文件夹2")})
})
public ResponseEntity<String> get() {
}
MD文件
另外扩展OpenAPI
输出格式添加扩展属性x-simple-markdown-files
,通过JSON
数组方式添加markdown
文件数据:
示例:
"x-simple-markdown-files": [{
"fileName": "1-CreditCard.md",
"title": "信用卡安全",
"content": "### 信用卡安全rnrn目前`PCI DSS`要求除了接口使用`https`之外,信用卡在实际传输过程中也需要加密传输,使用对称加密约定密码的方式加密后传输, 收到后在客户端执行解密操作。rnrn#### 加解密算法rnrn我们使用AES256加密,并以16进制格式输出为文本。加密密码与接口访问密码相同,在传输前对请求参数相关字段进行加密,rn收到响应结果后对相关字段解密后使用。",
"sortId": 1
}]
主题对象如下:
public class ExtendMarkdownFile implements Serializable {
private String fileName;
private String title;
private String content;
private Integer sortId;
}
待开发功能
还有些可能需要开发的功能,目前还在考虑中
-
文件夹复制、移动等功能
-
部分接口文档导出、分享功能
-
API
定义编辑功能(目前仅Markdown
文档可编辑,API
一般从其他系统生成是否有编辑必要) -
定时抓取日志查询功能