【springboot 开发工具】接口文档我正在使用它生成，舒坦

news2024/11/19 16:32:48

前言

先来描述下背景：由于新公司业务属于自研产品开发，但是发现各产品业务线对于接口文档暂时还是通过集成Swagger来维护，准确来说是knife4j（Swagger的增强解决方案）。但是对于5年的后端开发老说，早就厌倦了一个接口一个接口写到postman的重复操作了，所以必须搞个简便方式。

个人建议Swagger更适合用于一些对接口规范及维护要求较低的行业项目类软件开发，相对于开发而言，接口的文档生成及调试更加方便快捷。

所以这里结合个人之前的使用经验以及其他接口文档平台调研如下：

框架SwaggerYapiShowdocApiPost
代码侵入性强无无无
私有化部署支持支持支持不支持
是否开源是是是否
学习成本较高容易容易较高
自动生成文档支持插件支持需要客户端支持
数据Mock支持支持不支持（需要客户端）支持
自动化测试不支持支持需要客户端支持
数据导入不支持支持postman/swagger/har/json不支持支持postman
备注

当然还有其他很多可以用于接口文档维护的，像postman、RAP、EasyAPI等平台，文档型的像云雀、石墨文档、wiki等，各有优点以及适用的业务场景。

最后决定使用支持私有部署及swagger同步导入的开源平台 Yapi 来保存和维护各项目中的接口文档；当然不可避免，作为无偿的开源产品，它也会有一些瑕疵，比如目前开源维护度低（导致社区活跃度也相对减少很多）、平台中目录层级不支持二级以上（需要二次开发，一些fork版本虽然支持，但是版本较低）、一些版本存在的bug（参考issue）等。

但是这些都影响不大，最重要的还是考虑公司业务及技术团队的当前实际需求及后续扩展基本能很好的满足。

Yapi部署-docker

首先Yapi项目由去哪儿网开源在GitHub，官方文档中有详细的相关介绍，同时也有平台体验地址，这里不再过多赘述。

由于公司项目中已经使用docker来构建环境，所以这里主要介绍如何基于docker镜像来制作部署（非docker环境推荐官方提供的yapi-cli工具部署文档，简单易用，且无缝支持版本升级；而非一些博客文章，由于文章描述及水平参差不齐，可能会反向误导）。

其实docker部署的方式跟非docker基本相差不多，只是在流程上多了一个镜像制作，市面上也有一些博客文章也已经介绍过了，包括一些已经制作好并push的镜像，但是Yapi最新的1.10版本的镜像制作部署的文章暂时还没有发现，虽然看上去大同小异，但是实际操作下来还是有一些坑的；同时自己制作的镜像也更加放心安全。

首先我们了解到Yapi的环境要求：

  • nodejs（7.6+)
  • mongodb（2.6+）

MongoDB部署

因为接口的数据使用NoSQL数据库mongodb进行存储，所以我们首先需要安装部署mongodb。

1.下载官方镜像，这里版本选择4.2.6

docker pull mongodb:4.2.6

执行命令docker images可以看到镜像已经下载完成

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-bq60SEEd-1684404669318)(/Users/gzj/Library/Application Support/typora-user-images/image-20230518180628823.png)]

2.启动容器

 docker run  \
--name mongo \
-p 27017:27017  \
-v /data/yapi/mongodb/data/configdb:/data/configdb/ \
-v /data/yapi/mongodb/data/db/:/data/db/ \
-d mongo:4.2.6 --auth
  • -p 27017:27017：映射容器的访问端口。
  • -v 参数：将MongoDB容器中的数据挂载到外部目录，这样不可预料的意外导致容器无法恢复启动，也能保护原来的数据。
  • –auth：需要密码才能访问MongoDB。

使用命令docker ps可以看到容器已经正常启动

image-20230518180749104

3.设置用户密码

使用下面命令进入到容器中，并进入到MongoDB的命令行，同时切换到admin数据库

docker exec -it mongo mongo admin

image-20230518180826873

设置一个用户和密码，然后验证是否正确

db.createUser({ user:'admin',pwd:'123456',roles:[ { role:'userAdminAnyDatabase', db: 'admin'}"readWriteAnyDatabase"]});

# 验证
db.auth('admin', '123456')

image-20230518180911880

到这里MongoDB就部署完成了，后续注意对MongoDB的数据文件定时备份就行了（相关文章很多，这里不赘述了）。

Yapi部署

部署Yapi前，我们需要自己制作docker镜像，这里有两种方式

  • 源码编译
  • 官方yapi-cli工具

其中源码编译的方式稍微复杂点，对不同版本的环境依赖可能会产生一些坑，而且版本升级也相对麻烦点；这里推荐第二种方式，也就是yapi-cli。

1.编写Dockerfile

vi Dockerfile

# 内容
FROM node:11
RUN npm install -g yapi-cli --registry https://registry.npm.taobao.org

EXPOSE 3000 3000

2.编写docker-compose

这里使用docker-compose的方式制作镜像以及启动部署，

vi docker-compose.yml

# 内容
version: '3'

services:
  yapi:
    build:
      context: ./
      dockerfile: ./Dockerfile
    image: yapi:1.10.2
    container_name: yapi
    # 第一次启动使用
    command: "yapi server"
    # 之后使用下面的命令
    # command: "node /my-yapi/vendors/server/app.js"
    ports:
      - 3000:3000
      # 第一次启动时映射
      - 9091:9090
    volumes:
      - ./my-yapi:/my-yapi
  • dockerfile：执行当前目录下的Dockerfile来制作镜像。
  • image：命名镜像的名称及tag。
  • volumes：将容器中yapi的文件挂载到外部目录，包括配置文件。

这里注意，第一次启动的时候需要执行yapi-cli命令来帮助安装，所以需要使用command: "yapi server"及- 9091:9090，安装完成后重新执行docker-compose前把其注释即可。

3.制作镜像及安装

编写好所需要的文件之后，执行下面命令，

docker-compose up

首先会下载制作yapi镜像的基础镜像node:11

image-20230518180931394

下载完成后就能看到如下控制台，说明yapi-cli启动完成了

由于刚才我们将9090映射到9091端口，所以这里访问http://192.168.24.240:9091（192.168.24.240为宿主机的ip），能看到网页显示如下，

image-20230518180947857

接下来我们直接在上面设置好然后点击开始部署就可以安装我们想要的版本的yapi了，之后能看到页面以及控制台会不停刷安装的相关log，直到看到下面的信息这说明Yapi已经下载安装好了。

image-20230518181009029

4.启动

到这里就剩最后一步，下面我们直接退出控制台停止运行，由于之前- ./my-yapi:/my-yapi已经将Yapi文件挂载出来了，用ls命令能查看到当前目录下的my-yapi文件

进入目录后能看到config.json文件，它是Yapi的基础配置文件，可以设置管理员账号、MongoDB连接配置、邮箱通知等等，具体参考官方文档。

接下来修改docker-compose.yml如下，

version: '3'

services:
  yapi:
    build:
      context: ./
      dockerfile: ./Dockerfile
    image: yapi:1.10.2
    container_name: yapi
    # 第一次启动使用
    # command: "yapi server"
    # 之后使用下面的命令
    command: "node /my-yapi/vendors/server/app.js"
    ports:
      - 3000:3000
      # 第一次启动时映射
      # - 9091:9090
    volumes:
      - ./my-yapi:/my-yapi

修改完成后保存退出，使用下面命令就可以直接启动了，

docker-compose up -d
  • -d：后台启动

启动完成后，使用docker ps，能看到我们的Yapi容器已经启动完成了,

同时使用命令docker images也能看到我们制作好的1.10.2的镜像文件，

5.访问

启动完成后我们浏览器直接访问http://192.168.24.240:3000就能看到如下，

图片

接下来我们就用之前配置的管理员账户以及默认密码ymfe.org登录使用即可。

一些使用建议：

  1. 由管理员或各项目负责人添加不同项目分组，以及添加分组成员；
  2. 项目分组下以项目迭代版本来分类新建项目，通过项目命名携带版本号作为区分。
  3. 测试集合可以用于开发用例自测包括流程自动化测试，实际对于测试人员需求可能不太满足。

接口文档生成插件

虽然Yapi已经接管接口文档平台，满足开发团队对文档的维护需求了，但是我们知道大多数使用Swagger的开发可能最关注的点就是通过注解会自动生成接口文档，无需手动编写，提高了工作效率。

因为Yapi平台开放了相关API，所以同样支持外部生成，由于目前公司开发人员基本使用IDEA作为开发工具，暂时只调研了一些支持IDEA的插件。

综合使用及对比几个IDEA插件后，像YapiUpload、EasyYapi、Yapi X等，发现EasyApi插件的配置支持相对友好、文档生成时代码基本无侵入性、自定义功能强大等，同时满足项目接口文档生成较高的规范化需求；虽然自定义功能使用门槛较高，但是项目一次配置后基本无需改动，更多自定义规则配置及功能的详细使用请参考官网文档。

使用步骤：

  1. 打开File/Settings/Plugins搜索EasyYapi，选择install后重启IDEA;

    image-20230518181034019

  2. 打开File/Other Settings/EasyApi,在Yapi下配置server和tokens：

server 即部署的Yapi地址，如：http://192.168.20.24:3000
tokens 即yapi项目中用于请求项目openapi的私有token，获取方式为项目->设置->token 配置 -> 工具标识

  1. 三种生成接口文档并上传到Yapi的方式（初次使用可能会以弹窗的方式要求输入token）：
  • 打开项目中的包含api的文件或者在IDEA的左边项目文件区域选择文件或者文件夹 鼠标右键点击文件内容或文件夹, 选择ExportYapi 导出该文件或文件夹中所有的api;
  • 打开项目中的包含api的文件或者在IDEA的左边项目文件区域选择文件或者文件夹 使用快捷键alt shift E(windows)/ctrl E(mac) 然后选择要导出的API,选择导出渠道Yapi 点击[✔]按钮或者按回车键完成导出
  • 鼠标点击最上方Code > YapiDashBoard 然后就可以用鼠标将左边的API拖动到右边yapi目录中，完成API导出到Yapi

注意要生成相对规范的接口文档，需要编写较为完整的代码注释，如下(简单的注释Demo)：

/**
 * 分类名称
 * 分类备注/描述
 */
@RestController
@RequestMapping(value = "/demo")
public class DemoController {

    /**
    * api名称
    * api描述
    * @param param1 参数1的名称或描述
    * @param param2 参数2的名称或描述
    * @return
    */
    @GetMapping(value = "/test")
    public Result<Demo> methodName1(@RequestParam String param1,
                                    @RequestParam(required = false, defaultValue = "1") Integer param2){
        ...
    }

}

public class Demo {
    /**
     * 字段注释
     */
    private Long field1;
    /**
     * 如果使用javax.validation的话
     * 可以使用@NotBlank/@NotNull表示字段必须
     */
    private String field2;

    ...
}

通过插件上传后，即可在平台目录中看到所生成的接口文档。

使用建议：

  1. 通过插件来自动生成的接口文档需要自行查看生成的文档是否正确且规范，不正确或不规范的地方需要手动编辑修正。

  2. 一些全局的配置，可以在项目或模块目录下新建.yapi.config来进行配置(更对配置参考官方文档)

    # 参数忽视特定类
param.ignore=@java.lang.String
# 参数描述后缀
param.doc=groovy:",类型<"+tool.uncapitalize(it.type().name().replace("java.lang.","").replace("Long","String")) +">"
# Long转String
json.rule.convert[java.lang.Long]=java.lang.String
# 统一返回体
method.return[#return]=groovy: "com.xxx.xxx.Result<" + it.returnType() +">"

参考文档：
https://github.com/Ryan-Miao/docker-yapi

总结

以上就是今日分享的全部内容。希望能对大家的学习有所帮助，小伙伴们评论区留下“管用"，记得三联哦。 还有更多知识分享，欢迎拜访链接: 首页

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/541431.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

Java-线程安全的四个经典案例和线程池

Java-线程安全的四个经典案例和线程池

单例模式 有些对象&#xff0c;在一个程序中应该只有唯一 一个实例&#xff08;光靠人保证不靠谱 借助语法来保证&#xff09; 就可以使用单例模式 在单例模式下 对象的实例化被限制了 只能创建一个 多了的也创建不了 单例模式分为两种&#xff1a;饿汉模式和懒汉模式 饿汉模式…
阅读更多...
[Java基础]—SpringBoot

[Java基础]—SpringBoot

Springboot入门 Helloworld 依赖 <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.3.4.RELEASE</version> </parent><dependencies><depend…
阅读更多...
软件测试基础知识整理（四）- 软件开发模型、测试过程模型

软件测试基础知识整理（四）- 软件开发模型、测试过程模型

目录 一、软件开发模型 1.1 瀑布模型 1.1.1 特点 1.1.2 优缺点 1.2 快速原型模型&#xff08;了解&#xff09; 1.2.1 特点 1.2.2 优缺点 1.3 螺旋模型&#xff08;了解&#xff09; 1.3.1 特点 1.3.2 优缺点 二、测试过程模型 2.1 V模型&#xff08;重点&#xff…
阅读更多...
LeetCode_29. 两数相除

LeetCode_29. 两数相除

目录 题目描述 思路分析 我的题解 题目描述 给你两个整数&#xff0c;被除数 dividend 和除数 divisor。将两数相除&#xff0c;要求 不使用 乘法、除法和取余运算。 整数除法应该向零截断&#xff0c;也就是截去&#xff08;truncate&#xff09;其小数部分。例如&#xff…
阅读更多...
8个免费的高质量UI图标大全网站

8个免费的高质量UI图标大全网站

UI图标素材是设计师必不可少的设计元素。 高质量的UI图标会让设计师的设计效率事半功倍。 本文分享8个免费的高质量UI图标大全网站。 即时设计资源社区 即时设计资源广场中精选了多款专业免费的UI图标设计资源&#xff0c;无需下载即可一键保存源文件&#xff0c;同时还提供…
阅读更多...
深入浅析Linux Perf 性能分析工具及火焰图

深入浅析Linux Perf 性能分析工具及火焰图

Perf Event 子系统 Perf 是内置于 Linux 内核源码树中的性能剖析&#xff08;profiling&#xff09;工具。它基于事件采样的原理&#xff0c;以性能事件为基础&#xff0c;支持针对处理器相关性能指标与操作系统相关性能指标的性能剖析。可用于性能瓶颈的查找与热点代码的定位…
阅读更多...
Maven PKIX path building failed 错误提示

Maven PKIX path building failed 错误提示

最近公司的项目突然出现了下面的提示。 PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target -> [Help 2]问题和解决 出现上面的提示的问题是因为 SSL 签名的问题。 …
阅读更多...
经典面试题：理解Cookie和Session之间的区别

经典面试题：理解Cookie和Session之间的区别

文章目录 一、Cookie概念先知1、Cookie是什么&#xff1f;2、Cookie从哪里来&#xff1f;3、Cookie要存到哪里去&#xff1f;4、Cookie是存在哪里的&#xff1f;5、浏览器是如何通过Cookie来记录的&#xff1f;6、Cookie的过期时间有什么用&#xff1f; 二、见见Cookie三、会话…
阅读更多...
软件设计师考试笔记，已通过

软件设计师考试笔记，已通过

目录 系统可靠度 外部实体 内聚类型 编译过程 逆波兰式 前驱图 scrum框架模型 编译和解释 有限自动机 聚簇索引和非聚簇索引 二叉树的前序,中序,后序遍历 动态规划贪心算法 算法 01背包问题 系统可靠度 1. 串联部件可靠度 串联部件想要这条路走通&#xff0c;只有…
阅读更多...
软件测试行业7年了，薪资从10k到了22k，感觉到头了？

软件测试行业7年了，薪资从10k到了22k，感觉到头了？

蜕变之前 明天的希望&#xff0c;让我们忘了今天的痛苦。 怎样区别一个废柴和一个精英&#xff1f;看外貌&#xff0c;看气质&#xff0c;看谈吐&#xff0c;看消费… 有人忙着把人和人进行分类&#xff0c;有人忙着怎么从这一阶层过渡到上一阶层。当你很累的时候&#xff0c…
阅读更多...
引入外部文件实现步骤

引入外部文件实现步骤

1.引入数据库相关依赖 2.创建外部属性文件&#xff0c;properties格式&#xff0c;定义数据信息&#xff1a;用户名 密码 地址等 3.创建spring配置文件&#xff0c;引入context命名空间&#xff0c;引入属性文件&#xff0c;使用表达式完成注入 <beans xmlns"http://w…
阅读更多...
交友项目【集成环信Api】

交友项目【集成环信Api】

目录 1&#xff1a;自动装配 2&#xff1a;查询用户环信账户 3&#xff1a;环信ID查询用户信息 1&#xff1a;自动装配 在项目中集成环信API&#xff0c;完成即时通信等 环信官方文档地址&#xff1a;Java Server SDK [IM 开发文档] 自动装配模块&#xff1a; pom文件相关…
阅读更多...
2.数据结构期末复习之顺序表和链表

2.数据结构期末复习之顺序表和链表

1.表是可以是线性结构 学号姓名19(数据项)jams(数据项)20(数据项)ming(数据项) 19 jams或 20 ming是数据元表单个的是数据项‘’线性结构可以表示为 19 jams->20 ming2.什么是逻辑结构?:具有相同类型的有限序列(元素排序的位置,排兵布阵操作的方法) a1 a2 a3 .... an (空…
阅读更多...
jenkins流水线使用入门示例

jenkins流水线使用入门示例

之前采用Jenkins的自由风格构建的项目&#xff0c;每个步骤流程都要通过不同的方式设置&#xff0c;并且构建过程中整体流程是不可见的&#xff0c;无法确认每个流程花费的时间&#xff0c;并且问题不方便定位问题。 Jenkins的Pipeline可以让项目的发布整体流程可视化&#xf…
阅读更多...
低代码开发大势所趋，这款无代码开发平台你值得拥有

低代码开发大势所趋，这款无代码开发平台你值得拥有

文章目录 什么是低代码iVX和其它低代码的平台的区别没有创新的“拼凑”&#xff0c;没有好东西iVX在线编辑器体验 什么是低代码 低代码&#xff08;Low Code&#xff09;是一种可视化的应用开发方法&#xff0c;用较少的代码、以较快的速度来交付应用程序&#xff0c;将程序员…
阅读更多...
ElasticSearch漫游 (1.安装ELK)

ElasticSearch漫游 (1.安装ELK)

前期准备&#xff1a; 请搭建好linux环境 推荐使用centos7系统请关闭linux防火墙请安装好docker 安装ES 创建网络 我们需要部署kibana容器&#xff0c;因此需要让es和kibana互联&#xff0c;这里先创建一个网络。 docker network create es-net加载es镜像 运行docker命令 部…
阅读更多...
智能无线温振传感器：提高锂电设备故障诊断精度的利器

智能无线温振传感器：提高锂电设备故障诊断精度的利器

当今锂电工厂对于设备可靠性和生产效率的要求越来越高&#xff0c;而设备故障诊断是其中非常重要的一环。针对锂电设备的振动和温度等健康状态的监测&#xff0c;智能无线温振传感器是一款非常有用的工具。 图.太阳能面板生产&#xff08;iStock&#xff09; 智能无线温振传感器…
阅读更多...
和数组处理有关的一些OJ题（JAVA)(ArrayList）

和数组处理有关的一些OJ题（JAVA)(ArrayList）

1、给你一个数组 nums 和一个值 val&#xff0c;你需要 原地 移除所有数值等于 val 的元素&#xff0c;并返回移除后数组的新长度。 不要使用额外的数组空间&#xff0c;你必须确保时间复杂度为O(N)&#xff0c;空间复杂度为O&#xff0c;并原地修改输入数组。元素的顺序可以改…
阅读更多...
Android系统原理性问题分析 - Android Java框架层的结构

Android系统原理性问题分析 - Android Java框架层的结构

声明 在Android系统中经常会遇到一些系统原理性的问题&#xff0c;在此专栏中集中来讨论下。Android系统&#xff0c;为了能够更好的理解Android的Java世界的运行规律&#xff0c;此篇分析Android Java框架的结构。此篇参考一些博客和书籍&#xff0c;代码基于Android 7.1.1&a…
阅读更多...
资产处置求变，京东拍卖如何做好“价值枢纽”？

资产处置求变，京东拍卖如何做好“价值枢纽”？

近年来&#xff0c;随着资产处置市场规模快速成长以及互联网行业飞速发展&#xff0c;金融资产、司法拍卖、罚没物资等处置方式从最初单纯线下拍卖逐渐落地互联网&#xff0c;服务专业化程度也在不断提高。为更好适应市场变化&#xff0c;满足不断增长的市场需求&#xff0c;5月…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023