Spring Boot学习笔记-Spring Boot整合Swagger

2024-01-05 12:45:22

Spring Boot学习

官网：https://spring.io/projects/spring-boot#overview

文档：https://docs.spring.io/spring-boot/docs/2.2.6.RELEASE/reference/html/

参考视频：【狂神说Java】SpringBoot最新教程IDEA版通俗易懂_哔哩哔哩_bilibili

项目完整参考代码：lexiaoyuan/SpringBootStudy: My Spring Boot study notes (github.com)、SpringBootStudy: 我的Spring Boot学习笔记 (gitee.com)

Spring Boot整合Swagger

Swagger介绍

官网：https://swagger.io/

整合Swagger

首先新建一个Spring Boot项目，引入web模块
再引入整合Swagger需要的依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

在主启动类上添加一个注解，开启Swagger2

@EnableSwagger2  // 开启Swagger2

现在运行项目，访问：http://localhost:8080/swagger-ui.html，就可以看到Swagger已经开启了，只是现在还没有配置其他的接口注解

Swagger的配置

新建一个config包，在config包下新建SwaggerConfig.java

@Configuration
public class SwaggerConfig {
}

配置API文档的信息

// 开启Swagger的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

private ApiInfo apiInfo(){
    // 作者信息
    Contact contact = new Contact("乐小猿", "http://www.lexiaoyuan.club", "2775886918@foxmail.com");

    // Api信息
    return new ApiInfo(
        "乐小猿的SwaggerAPI文档"
        , "这是学习使用Swagger的文档"
        , "v1.0"
        , "http://www.lexiaoyuan.club"
        , contact
        , "Apache 2.0"
        , "http://www.apache.org/licenses/LICENSE-2.0"
        , new ArrayList<>());
}

再运行项目，访问：http://localhost:8080/swagger-ui.html，可以看到，关于这个项目的API文档说明的信息已修改

配置配置扫描接口的方式和要扫描的包：
首先新建一个controller包，controller包下新建一个HelloController.java

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello Swagger";
    }
}

再在docket()方法中配置

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // RequestHandlerSelectors：配置扫描接口的方式
            // basePackage:指定要扫描的包
            // 要写在.select()和.build()中间
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.springboot.controller"))
            .build();
}

再运行项目，访问：http://localhost:8080/swagger-ui.html#/，只显示了controller包下的接口

扫描实体类：
新建一个pojo包，在pojo包下新建一个User.java

@ApiModel("用户实体类")   // API文档的Model中会显示中文注释
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

在HelloController.java中增加一个请求

// 只要我们在请求接口的返回值中存在实体类，其就会被扫描到Swagger中
@GetMapping("/user")
public User user(){
    return new User();
}

再运行项目，访问：http://localhost:8080/swagger-ui.html#/

过滤路径：添加.paths(PathSelectors.ant("/hello/**"))

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // RequestHandlerSelectors：配置扫描接口的方式
            // basePackage:指定要扫描的包
            // 要写在.select()和.build()中间
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.springboot.controller"))
            // paths():过滤什么路径
            .paths(PathSelectors.ant("/hello/**")) //只有/hello/路径下的才能扫描到
            .build();
}

再运行项目，访问：http://localhost:8080/swagger-ui.html#/，只显示/hello下的请求

配置多个分组：添加.groupName("乐小猿")

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("乐小猿")
        // RequestHandlerSelectors：配置扫描接口的方式
        // basePackage:指定要扫描的包
        // 要写在.select()和.build()中间
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.springboot.controller"))
        // paths():过滤什么路径
        .paths(PathSelectors.ant("/hello/**")) //只有/hello/路径下的才能扫描到
        .build();
}

// 配置多个分组
@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");
}

再运行项目，访问：http://localhost:8080/swagger-ui.html#/，选择不同的分组，可以显示不同配置下的文档

配置是否开启Swagger，常用在不同环境切换时使用，在开发环境下开启Swagger，在产品环境下关闭Swagger：
首先在resources目录下新建application-dev.properties和application-pro.properties

# application-dev.properties
server.port=8081

# application-pro.properties
server.port=8082

再在application.properties中激活需要的环境

spring.profiles.active=dev

再添加 .enable()

// 开启Swagger的bean实例
@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())
            .groupName("乐小猿")
            .enable(flag)// 是否开启Swagger
            // RequestHandlerSelectors：配置扫描接口的方式
            // basePackage:指定要扫描的包
            // 要写在.select()和.build()中间
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.springboot.controller"))
            // paths():过滤什么路径
            .paths(PathSelectors.ant("/hello/**")) //只有/hello/路径下的才能扫描到
            .build();
}

注意：

// 注意Environment的包不要导错了
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;

再运行项目，访问：http://localhost:8081/swagger-ui.html，注意：这里的端口号应该是8081

修改application.properties

spring.profiles.active=pro

注释掉配置的多个分组

 // 配置多个分组
/* @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");
 }*/

再运行项目，访问：http://localhost:8082/swagger-ui.html，注意：这里的端口号应该是8082，会提示

OK，环境的切换完成
再补充几个注解，在HelloController.java中添加

@PostMapping("/hello2")
@ApiOperation("Hello 接口")   // Operation是放在接口方法上
public String hello2(@ApiParam("用户名") String username) {
    return "Hello "+username;
}