前言：

本文内容：Swagger介绍及集成、配置Swagger信息、配置Swagger扫描接口及开关

推荐免费SpringBoot基础教程视频：【狂神说Java】SpringBoot最新教程通俗易懂_哔哩哔哩_bilibili

Swagger介绍及集成

Swagger简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

  • 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，节约写文档的时间。
  • 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

Swagger：API Documentation & Design Tools for Teams | Swagger

常用测试接口工具：Postman

SpringBoot集成Swagger

  1. 新建项目springboot-08-swagger，并勾选Spring Web

  2. 在pom中引入Swagger依赖

    Swagger3.0和Swagger2.0的差别较大，具体参考Swagger - Version 3.0.3

    这里使用Swagger2.9.2

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    <!-- 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>
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

  3. 在controller包下新建HelloController.java来测试

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    package com.jokerdig.controller;

    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;

    /**
     * @author Joker大雄
     * @data 2022/7/28 - 12:01
     **/
    @RestController
    public class HelloController {

        @RequestMapping(value="/hello")
        public String hello(){
            return "hello";
        }
    }

  4. 在config包下新建SwaggerConfig.java，来配置Swagger

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    package com.jokerdig.config;

    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;

    /**
     * @author Joker大雄
     * @data 2022/7/28 - 12:04
     **/
    @Configuration
    @EnableSwagger2 // 开启swagger2
    public class SwaggerConfig {
    }

  5. 在resources下新建application.yaml，并解决swagger2.6.x与Spring Boot不兼容的问题

    1
    2
    3
    4
    5
    # 解决swagger2.6.x与springboot不兼容的问题
    spring:
      mvc:
        pathmatch:
          matching-strategy: ant_path_matcher

  6. 运行测试

    http://localhost:8080/swagger-ui.html

配置Swagger信息

  1. 在SwaggerConfig中进行自定义配置

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    package com.jokerdig.config;

    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.service.VendorExtension;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;

    import java.util.ArrayList;

    /**
     * @author Joker大雄
     * @data 2022/7/28 - 12:04
     **/
    @Configuration
    @EnableSwagger2 // 开启swagger2
    public class SwaggerConfig {

        // 配置Swagger的Docket @Bean实例
        @Bean
        public Docket docket(){
            return new Docket(DocumentationType.SWAGGER_2)
                	// 配置apiInfo
                    .apiInfo(apiInfo());
        }
        // 配置Swagger信息 apiInfo
        private ApiInfo apiInfo(){
            return new ApiInfo("Jokerdig.com Swagger AIP", "一个代码小白的成长", "1.0", "https://jokerdig.com",
                    new Contact("JokerDaxiong", "https://jokerdig.com", "xxx@gmail.com"), "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());
        }
    }

  2. 运行测试

    http://localhost:8080/swagger-ui.html

配置Swagger扫描接口及开关

配置扫描接口

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        // 配置apiInfo
        .apiInfo(apiInfo())
        // 配置扫描接口 RequestHandlerSelectors
        // 通过basePackage() 指定要扫描的包
        // any() 扫描全部
        // none() 不扫描
        // withClassAnnotation() 扫描类上的注解
        // withMethodAnnotation() 扫描方法上的注解
        .select()
        .apis(RequestHandlerSelectors
              .basePackage("com.jokerdig.controller"))
        // paths() 过滤路径
        .paths(PathSelectors.ant("/jokerdig/**"))
        .build()
        ;
}

配置是否启动Swagger

1
2
3
4
5
6
7
8
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        // 配置apiInfo
        .apiInfo(apiInfo())
        // 是否开启swagger true开启 false关闭
        .enable(true);
}

小练习

在生产环境中启用swagger，在发布环境中关闭swagger？

  1. 编辑application.yaml，并新建application-dev.yaml和application-pro.yaml

    application

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    # 解决swagger2.6.x与springboot不兼容的问题
    spring:
      mvc:
        pathmatch:
          matching-strategy: ant_path_matcher
    # 配置开发环境
      profiles:
        active: dev
    server:
      port: 8080

    application-dev

    1
    2
    3
    4
    5
    6
    7
    # 解决swagger2.6.x与springboot不兼容的问题
    spring:
      mvc:
        pathmatch:
          matching-strategy: ant_path_matcher
    server:
      port: 8081

    application-pro

    1
    2
    server:
      port: 8082

  2. 在SwaggerConfig中进行配置

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    // 配置Swagger的Docket @Bean实例
    @Bean
    public Docket docket(Environment environment){

        // 设置要返回的环境 dev开发环境 pro发布环境
        Profiles profiles = Profiles.of("dev");
        // 获取项目环境
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
            // 配置apiInfo
            .apiInfo(apiInfo())
            // 是否开启swagger true开启 false关闭
            // 这里通过flag返回的布尔值来监听，并根据环境打开或关闭swagger
            .enable(flag);
    }

  3. 运行测试

    注意端口号的变化

    http://localhost:8081/swagger-ui.html

    可以动态的控制swagger开关