简单API文档服务发布

最近使用新OpenAPI接口时发现自带的SwaggerUI界面不是很友好,一些开源的库,如Knife4j使用虽然很方便,不过对于比较大的schema支持不好,容易出现卡顿,目前做的比较好的是ApiFox,不过不能同步Markdown文件,而且私有化部署需要另外收费。

其实API文档服务比较简单,没有太多功能,因此抽空自己开发一个简单的API文档系统

功能介绍

由一个Java后端和Vue3前端组成,主要功能如下:

  1. Swagger或者OpenAPI的文档(json/yaml)文件或URL路径导入文档系统
  2. 支持查看Markdown文档和API文档字段等
  3. 支持新增Markdown文档,方便对OpenAPI文档做一些附加说明等
  4. 支持分享链接和密码查看,支持分享有效期
  5. 支持定时从指定URL抓取文档数据
  6. 支持在线调试接口请求
  7. 支持多级文件夹展示API文档

实现技术栈

基于Spring Boot开发的文档服务器,主要要两个项目:

  1. 后台服务simple-api-doc
  2. UI界面simple-api-doc-uiVue3

最后打包的时候合并到一个项目中,成为一个jar包,最后打包成为一个zip文件,加压运行即可。

源码:https://github.com/fugary/simple-api-doc

后端框架

  1. Spring Boot
  2. MybatisMybatisPlus
  3. Lombok
  4. Logback
  5. FlywayDB
  6. swagger-parser

前端系统

基于自己对element-plus的二次封装:https://github.com/fugary/simple-element-plus-template

  1. Vue3全家桶
  2. element-plus
  3. dayjs
  4. lodash-es
  5. monaco-editor
  6. md-editor-v3编辑Markdown编辑器
  7. markdown-it

安装启动

开源地址:https://github.com/fugary/simple-api-doc

解压启动

找到https://github.com/fugary/simple-api-doc/releases

下载最新版本后解压

简单API文档服务发布

进入bin目录

简单API文档服务发布

点击start.bat启动后可以进入登录页面:http://localhost:9089/

简单API文档服务发布

如果要支持MySQL需要提前配置MySQL数据库信息。

Docker启动

docker运行比较简单,只要已经安装好docker,直接使用命令就可以自动拉去镜像并运行了

docker run -p 9089:9089 fugary/simple-api-doc:latest

常规使用

系统后台管理API接口,通过分享链接的形式提供给客户

修改密码

启动后进入系统,登录账号admin/12345678,登录系统后尽快进入【个人资料】修改密码

简单API文档服务发布

导入数据

点击【导入数据】,选择需要导入的jsonyaml文件,或者指定的URL地址,如果需要认证的话可以根据实际情况去填写信息,支持BasicToken认证方式。

这里以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

简单API文档服务发布

导入后可以查看文档详情:

简单API文档服务发布

左侧文件夹区域,按照Tag作为文件夹展示,右侧是主文档区域,可以分享文档导入数据调试接口

文档分享

导入的文档并不是直接对外开放,需要新建一个【文档分享】,通过文档分享链接提供给第三方客户,支持密码和有效期控制

进入【文档分享】页面,点击【新增】按钮,填写分享信息,可以填写名称,以及一些常用配置信息:

简单API文档服务发布

新建好之后就有一个分享链接,可以把链接给到第三方使用:

简单API文档服务发布

分享查看

复制好分享链接或者直接从分享列表页点击可以跳转到分享页面,分享页面可以【调试接口】,下载Swagger支持的json或者yaml接口文档

简单API文档服务发布

右侧是请求体或响应体详细文档信息

简单API文档服务发布

接口调试

目前支持简单的接口调试功能,点击【调试接口】,弹出的新窗口可以选择【发送请求】

简单API文档服务发布

高级功能

定时导入

简单API文档服务发布

定时导入只支持从URL抓取数据,配置一些定时相关信息即可:

简单API文档服务发布

多级文件夹

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;
}

待开发功能

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

  1. 文件夹复制、移动等功能

  2. 部分接口文档导出、分享功能

  3. API定义编辑功能(目前仅Markdown文档可编辑,API一般从其他系统生成是否有编辑必要)

  4. 定时抓取日志查询功能

给TA打赏
共{{data.count}}人
人已打赏
运维

Nginx启用Status状态页面

2023-11-21 16:28:32

运维

使用Picgo+Github图床+Typora实现Markdown笔记

2024-11-19 10:36:01

0 条回复 A文章作者 M管理员
    暂无讨论,说说你的看法吧
个人中心
购物车
优惠劵
今日签到
有新私信 私信列表
搜索