简单API文档服务发布 – Gary的个人技术记录

最近使用新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

这个地址不能直接访问，可能需要代理下载下来后使用，或者用代理工具：

https://mirror.ghproxy.com/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": "### 信用卡安全\r\n\r\n目前`PCI DSS`要求除了接口使用`https`之外，信用卡在实际传输过程中也需要加密传输，使用对称加密约定密码的方式加密后传输， 收到后在客户端执行解密操作。\r\n\r\n#### 加解密算法\r\n\r\n我们使用AES256加密，并以16进制格式输出为文本。加密密码与接口访问密码相同，在传输前对请求参数相关字段进行加密，\r\n收到响应结果后对相关字段解密后使用。",
    "sortId": 1
}]

主题对象如下：

public class ExtendMarkdownFile implements Serializable {
    private String fileName;
    private String title;
    private String content;
    private Integer sortId;
}

待开发功能

还有些可能需要开发的功能，目前还在考虑中

文件夹复制、移动等功能
部分接口文档导出、分享功能
API定义编辑功能（目前仅Markdown文档可编辑，API一般从其他系统生成是否有编辑必要）
定时抓取日志查询功能