Swagger入门
学习目标：
- 了解Swagger的作用和概念
- 了解前后端分离
- 在Spring中集成Swagger
Swagger简介
- 前后分离：
- 前端测试后端接口：postman
- 后端提供接口，需要实时更新的消息和改动！
Swagger
- Api框架；
- RestFul Api 文档在线自动生成工具==>Api文档与API自定义同步更新
- 直接运行，可以在线测试API接口
在项目使用Swagger需要Springbox
- swagger2
- ui
SpringBoot集成Swagger
- 1、新建springboot-web项目
- 2、导入相关依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- 3、编写一个Hello工程
- 4、配置Swagger == > Config
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}
<?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.it</groupId>
<artifactId>swagger-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger-demo</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<spring-boot.version>2.3.7.RELEASE</spring-boot.version>
</properties>
<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>
<exclusions>
<exclusion>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<encoding>UTF-8</encoding>
</configuration>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>2.3.7.RELEASE</version>
<configuration>
<mainClass>com.it.SwaggerDemoApplication</mainClass>
</configuration>
<executions>
<execution>
<id>repackage</id>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
配置Swagger
Swagger的bean实例Docket；
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
/**
* 配置了swagger的Docket的bean实例
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
/**
* 配置swagger信息=apiInfo
*/
private ApiInfo apiInfo(){
/**
* 作者信息
*/
Contact contact = new Contact("谦","http://blog.kuangstudy.com/","24736743@qq.com");
return new ApiInfo(
"狂神的Swagger Api文档",
"世界和平",
"v1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
Swagger配置扫描接口
- Docket.select()
/**
* 配置了swagger的Docket的bean实例
* .enable 是否启用Swagger，如果为false，则Swagger不能再浏览器中使用
* @return
*/
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors,配置扫描接口的方式
//basePackage:指定扫描的包
//any():扫描全部
//none():不扫描
//withClassAnnotation: 扫描类上的注解,参数是一个注解的反射对象
//withMethodAnnotation: 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.st.controller"))
//paths(). 过滤什么路径
.paths(PathSelectors.ant("/st/**"))
.build(); //build
}
只希望Swagger在生产环境中使用，在发布的时候不使用？
- 判断是不是生产环境
- 注入enable(flag)
/**
* 配置了swagger的Docket的bean实例
* .enable 是否启用Swagger，如果为false，则Swagger不能再浏览器中使用
* @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)
.apiInfo(apiInfo())
.enable(flag)
.select()
//RequestHandlerSelectors,配置扫描接口的方式
//basePackage:指定扫描的包
//any():扫描全部
//none():不扫描
//withClassAnnotation: 扫描类上的注解,参数是一个注解的反射对象
//withMethodAnnotation: 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.st.controller"))
//paths(). 过滤什么路径
.paths(PathSelectors.ant("/st/**"))
.build(); //build
}
配置Api文档的分组
return new Docket(DocumentationType.SWAGGER_2)
.groupName("xx");
如何配置多个分组;
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
