一分钟完成springboot项目整合Swagger2实现自动生成接口文档

Posted 2023-03-01

参考技术A 一份好的接口文档能够让接口调用者很清晰的知道如何调用一个API接口，包括请求方式、传参规范、接口返回信息等；也能帮助团队新人快速了解业务。

传统的做法是由开发人员维护一个API接口文档，一般是一个word文档或一个提供接口文档管理的网站。这种做法有很多弊端：文档难以维护、浪费开人员时间、文档难以与接口保持一致等。

Swagger2的出现很好的解决了上述问题，可以实现接口文档实时在线生成，提供在线接口测试功能。唯一的弊端就是对接口程序有侵入，但本人认为还是利大于弊的。

接下来我们将Swagger2整合到springboot项目中，并用swagger-bootstrap-ui对Swagger2进行界面美化，废话不多说，我们开始。。。

在pom.xml中导入

在application.yml中设置swagger2是否开启的开关，关闭后接口文档被关闭，在生产环境部署时就需要关闭接口文档。

1.创建注解SwaggerCustomIgnore.java，主要用于忽略某些不想生成接口文档的接口。

2.创建配置类SpringfoxSwagger2Config.java，配置Swagger接口文档生成规则和过滤规则。

3.拦截器排除swagger相关资源，新建或修改WebConfig.java文件，内容如下。

1.编写内容参考如下

2.注解说明

启动项目，浏览器输入http://location:8081/doc.html,效果如下。

每天五分钟写K8：SpringBoot与mysql整合

在第一节中我们创建了mysql的Service，上一节我们运行了Spring-boot的项目。这一节我们将两个项目结合起来，让spring-boot访问mysql服务。

一、给Spring-boot项目的Deployment添加环境变量

Kubernetes运行着大量的Service，那么必然需要服务发现机制。由于一个Service的Cluster IP不会发生改变，那么Kubenetes就使用了环境变量来解决了这个问题。使用时将要使用的服务添加到环境变量即可。在上节的yaml文件中修改spec.template.spec.containers项即可。

containers: - name: springboot-demo image: k8s-boot:2.0 imagePullPolicy: Never ports: - containerPort: 8080 env:    - name: MYSQL_SERVICE_HOST value: 'mysql' - name: MYSQL_SERVICE_PORT value: '3306'

二、准备可访问数据的Spring-boot项目

spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://${MYSQL_SERVICE_HOST:localhost}:${MYSQL_SERVICE_PORT:3306}/test?useUnicode=true&characterEncoding=utf-8 username: root password: 123456

三、按上节部署方式进行部署

上传镜像是一个比较繁琐的工作，我提供了上传到指定主机的脚本image_deploy.py在github上。

部署完成后在浏览器中测试：http://<node IP>:30000/user/findAll。最终会返回以下错误：

java.sql.SQLSyntaxErrorException: Unknown database 'test'

这是因为我们的数据库服务尚未进行正确的初始化。

四、初始化数据库

初始化数据库有很多种方式，例如:

• 暴露Service的NodePort，然后用图形化客户端连接，执行SQL语句

• 在Pod中运行mysql客户端，执行SQL语句

• 借助ConfigMap，启动Pod时获取初始化SQL语句并执行

第一种咱们已经接触过了，第三种尚未学习。今天我们就采用第二种初始化。

第一步要获取mysql pod的名称：

$ kubectl get pod  -l app=mysqlNAME READY STATUS RESTARTS AGEmysql-qkfcd 1/1 Running 0 4d22h

第二步进入容器：

$ kubectl exec -it mysql-qkfcd /bin/bashroot@mysql-qkfcd:/#

第三步连接mysql服务，执行SQL

root@mysql-qkfcd:/$ mysql -uroot -pEnter password:Welcome to the MySQL monitor. Commands end with ; or \g.Your MySQL connection id is 18Server version: 8.0.17 MySQL Community Server - GPL
Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or itsaffiliates. Other names may be trademarks of their respectiveowners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql> create database test;Query OK, 1 row affected (0.00 sec)
mysql> use test;Database changedmysql> CREATE TABLE `user` ( -> `id` int(11) NOT NULL AUTO_INCREMENT, -> `user_name` varchar(45) NOT NULL, -> `password` varchar(45) NOT NULL, -> PRIMARY KEY (`id`) -> ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;Query OK, 0 rows affected, 1 warning (0.01 sec)
mysql> exit

最后退出即可。

代码下载：

https://github.com/loveoobaby/blog_code