SpringBoot集成swagger（3.0.0版本）
河南循中网络科技有限公司 - 精心创作，详细分解，按照步骤，均可成功！
文章目录
- swagger介绍
- 学习资料
- Swagger配置
- ！！到这里，swagger则配置完成，接下来是测试！！
- 结合[MyBatisPlus代码生成器](https://blog.csdn.net/ChinaYangJu/article/details/126209506)，测试Swagger
-
- mp的pom文件
- system的pom文件
- 修改启动类
- 创建测试类测试swagger
- swagger注解
swagger介绍
一般开发人员在对接前后端的时候，都需要提供相应的接口文档。但对于后端来说，编写接口文档是非常费事费力的，有时候甚至写文档所损耗的时间比写代码付出的还要多，并且还会经常因为没有及时更新，导致前端对接的时候，就会出现实际接口与文档不一致，而且手写接口文档还容易出错，而swagger则是能很好的解决了这个痛点。
Swagger 是一个规范完整的框架，用于生成、描述、调用和可视化 RESTful 风格的Web服务。可用作于接口的文档在线自动生成和功能的测试。
学习资料
【【狂神说Java】一小时掌握Swagger技术-哔哩哔哩】
swagger官网
Swagger配置
- 引入swagger的jar包，注意需要web工程。
<!-- 版本控制 -->
<properties>
<!-- swagger -->
<springfox-boot-starter.version>3.0.0</springfox-boot-starter.version>
</properties>
<!-- 引入的jar包 -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>${springfox-boot-starter.version}</version>
</dependency>
</dependencies>
- 创建SwaggerConfig配置类。
package com.xz.swagger;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
/**
* swagger配置
* 访问地址：项目路径前缀/swagger-ui/index.html
*/
@Configuration
@EnableWebMvc
public class SwaggerConfig {
/**
* 配置了swagger的Docket的bean实例
* 此方法可配置多个，复制后改个方法名即可，用于分组
* @return
*/
@Bean
public Docket docket(Environment environment){
//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev","test");
//通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.groupName("河南循中网络科技有限公司")
.apiInfo(apiInfo())
.enable(flag)//enable是否启动Swagger，如果为false，则Swagger不能在浏览器中访问
.select()
//RequestHandlerSelectors.basePackage("包名") 单包扫描
//RequestHandlerSelectors.basePackage("包名").or(RequestHandlerSelectors.basePackage("包名")) 多包扫描
.apis(RequestHandlerSelectors.basePackage("com.xz.controller.miniPro"))
//加了ApiOperation注解的类，才生成接口文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();
}
/**
* 配置swagger信息=apiInfo
* @return
*/
private ApiInfo apiInfo(){
Contact contact = new Contact("项目组成员", "", "[email protected]");
return new ApiInfo(
"swaggerAPI文档",
"在高处有如临深渊的谨慎，在低谷有仰望星空的勇气。",
"v1.0",
"",
contact,
"Apache Tomcat/9.0.64",
"https://tomcat.apache.org/tomcat-9.0-doc/building.html",
new ArrayList<>());
}
}
！！到这里，swagger则配置完成，接下来是测试！！
结合MyBatisPlus代码生成器，测试Swagger
mp的pom文件
子模块mp需引用分模块common，因为swagger的jar包和配置都存在与common模块中。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.xz</groupId>
<artifactId>mp</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>mp</name>
<description>河南循中网络科技有限公司 - MyBatis-Plus自动化</description>
<!-- 子模块打包类型必须为jar -->
<packaging>jar</packaging>
<!-- parent指明继承关系，给出被继承的父项目的具体信息 -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.7.1</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<!-- 版本控制 -->
<properties>
<java.version>1.8</java.version>
<!-- 实体类注解 -->
<lombok.version>1.18.24</lombok.version>
<!-- 数据库 -->
<druid-spring-boot-starter.version>1.2.11</druid-spring-boot-starter.version>
<!-- mybatis plus -->
<mybatis-plus-boot-starter.version>3.5.1</mybatis-plus-boot-starter.version>
<!-- mybatis代码生成器 -->
<mybatis-plus-generator.version>3.5.3</mybatis-plus-generator.version>
<!-- mybatis代码生成器，所需要的“velocity模板引擎” -->
<velocity-engine-core.version>2.3</velocity-engine-core.version>
</properties>
<!-- 引入的jar包 -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!-- 引用分模块common -->
<dependency>
<groupId>com.xz</groupId>
<artifactId>common</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
<!-- 实体类注解 -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>${lombok.version}</version>
</dependency>
<!-- 数据库 -->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>druid-spring-boot-starter</artifactId>
<version>${druid-spring-boot-starter.version}</version>
</dependency>
<!-- mybatis plus -->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
<version>${mybatis-plus-boot-starter.version}</version>
</dependency>
<!-- mybatis代码生成器 -->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-generator</artifactId>
<version>${mybatis-plus-generator.version}</version>
</dependency>
<!-- mybatis代码生成器，所需要的“velocity模板引擎” -->
<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity-engine-core</artifactId>
<version>${velocity-engine-core.version}</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
system的pom文件
子模块system需引用分模块mp
com.xz
mp
0.0.1-SNAPSHOT
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.xz</groupId>
<artifactId>system</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>system</name>
<description>河南循中网络科技有限公司 - 程序</description>
<!-- 子模块打包类型必须为jar -->
<packaging>jar</packaging>
<!-- parent指明继承关系，给出被继承的父项目的具体信息 -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.7.1</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<!-- 版本控制 -->
<properties>
<java.version>1.8</java.version>
</properties>
<!-- 引入的jar包 -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!-- 引用分模块common -->
<dependency>
<groupId>com.xz</groupId>
<artifactId>common</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
<!-- 引用分模块mp -->
<dependency>
<groupId>com.xz</groupId>
<artifactId>mp</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
修改启动类
只为启动起来后，更方便查阅相关URL
package com.xz;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.core.env.Environment;
import java.net.InetAddress;
@SpringBootApplication
public class SystemApplication {
public static void main(String[] args) {
try {
ConfigurableApplicationContext application = SpringApplication.run(SystemApplication.class, args);
Environment env = application.getEnvironment();
String ip = InetAddress.getLocalHost().getHostAddress();
String port = env.getProperty("server.port");
System.out.println("\n----------------------------------------------------------\n\t" +
"应用程序 系统平台端 正在运行! 访问地址:\n\t" +
"本机: \t\t http://localhost:" + port + "/\n\t" +
"外部访问: \t http://" + ip + ":" + port + "/\n\t" +
"Swagger文档: \t http://" + ip + ":" + port + "/swagger-ui/index.html\n" +
"----------------------------------------------------------");
}catch (Exception e){
e.printStackTrace();
}
}
}
创建测试类测试swagger
swagger注解
swagger是通过注解表明该接口需要生成文档，其中包含（接口名、请求方法、参数、返回信息）
如下注解介绍，只介绍有用的干货，无用的信息，暂不介绍
| 注解 | 说明 |
|---|---|
| @Api(tags=“说明该类的作用”) | 修饰整个类，描述Controller的作用 |
| @ApiOperation(value = “说明方法的作用”,notes = “方法的备注说明”,response = 接口返回参数类型) | 修饰一个类下的一个方法，描述Controller下接口的作用 |
| @ApiImplicitParam(name = “参数名”,value = “参数说明”,dataType = “字段类型”,defaultValue = “参数的默认值”,required = 参数是否必传true、false) | 修饰一个类下的一个方法，当只有一个请求参数时使用 |
| @ApiImplicitParams({@ApiImplicitParam(),@ApiImplicitParam()}) | 修饰一个类下的一个方法，当有多个请求参数时，配合@ApiImplicitParam一起使用 |
| @ApiModel(value=“为模型提供备用名称”, description=“提供详细的描述”) | 修饰整个类，描述模型的作用，用于模型类 |
| @ApiModelProperty(value = “属性简要说明”) | 修饰整个类，描述模型下属性的作用，用于模型类的属性上 |