Swagger配置与使用

文章目录

前言

作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。

一、简介

官网：https://swagger.io/
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
Swagger 的优势

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

二、基本使用

1. 导入相关依赖

通过在项目中引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-web</artifactId>
            <version>2.9.2</version>
        </dependency>
        <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>

2. 编写配置文件

在配置文件 config 目录下，添加 swagger 的配置文件 SwaggerConfig.java

@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
}

这个时候 Swagger 已经算是整合到项目之中了，可以启动下服务，输入http://localhost:8080/swagger-ui.html# （这里我的项目端口是 8868 ，项目路径是 /mike，所以我打开的文档地址为http://localhost:8868/mike/swagger-ui.html# ）即可查看 swagger 文档。

可以看到 Swagger 文档中大概有这四类信息

• 组
• 基本信息
• 接口信息
• 实体类信息

2.1 配置基本信息

Swagger 有自己的实例 Docket，如果我们想要自定义基本信息，可以使用 docket 来配置 swagger 的基本信息，基本信息的设置在 ApiInfo 这个对象中。

Swagger 默认的基本信息展示

ApiInfo 中默认的基本设置

• title：Api Documentation
• description：Api Documentation
• version：1.0
  termsOfServiceUrl：urn:tos
  contact：无
  license：Apache 2.0
  licenseUrl：http://www.apache.org/licenses/LICENSE-2.0

SwaggerConfig.java 配置文件添加以下内容：

    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置基本信息
                .apiInfo(apiInfo());
    }

    // 基本信息设置
    private ApiInfo apiInfo() {
        Contact contact = new Contact(
                "程农", // 作者姓名
                "https://www.csdn.net/?spm=1001.2014.3001.4476", // 作者网址
                "307502005@qq.com"); // 作者邮箱
        return new ApiInfoBuilder()
                .title("多加辣-接口文档") // 标题
                .description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述
                .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
                .version("1.0") // 版本
                .license("Swagger-的使用(详细教程)")
                .licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535")
                .contact(contact)
                .build();
    }

重启服务，打开 Swagger 文档，基本信息改变如下所示：

2.2 配置接口信息

默认情况下，Swagger 是会展示所有的接口信息的，包括最基础的 basic-error 相关的接口

有时候我们希望不要展示 basic-error-controller 相关的接口，或者是说这想要显示某些接口，比如说：user-controller 下的接口，由该怎么去实现呢？这个时候就需要设置 扫描接口

    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)

                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                        //.any() // 扫描全部的接口，默认
                        //.none() // 全部不扫描
                        .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
                        //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                        //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口

                )
                .paths(PathSelectors
                        .any() // 满足条件的路径，该断言总为true
                        //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                        //.ant("/user/**") // 满足字符串表达式路径
                        //.regex("") // 符合正则的路径
                )
                .build();
    }

可根据自己的需求去设置对应的配置，这里我就不再一一赘述了，以上是我所设置的配置，重启服务，打开 Swagger 文档，接口信息改变如下所示：
可以看到之前 basic-error-controller 相关的接口已经没有了

2.3 配置分组信息

Swagger 默认只有一个 default 分组选项，如果没有设置，所有的接口都会显示在 default `分组下，如果功能模块和接口数量一多，就会显得比较凌乱，不方便查找和使用。
swagger 文档中组名默认是 default，可通过 .groupName(String )

    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("mike") // 修改组名为 "mike"
                ;
    }

修改后：
如果需要配置多个组的话，就需要配置多个 docket() 方法，这里我就简单写两组，代码如下：

    /**
     * 展示 controller 包下所有的接口
     */
    @Bean
    public Docket docket1() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("mike") // 修改组名为 "mike"
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                        .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
                )
                .paths(PathSelectors
                         .any() // 满足条件的路径，该断言总为true
                )
                .build();
    }

    /**
     * 展示路径为 /error 的所有接口（基础接口）
     */
    @Bean
    public Docket docket2() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("yank") // 修改组名为 "yank"
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                        .any() // 扫描全部的接口，默认
                )
                .paths(PathSelectors
                        .ant("/error") // 满足字符串表达式路径
                )
                .build();
    }

重启服务，打开 Swagger 文档，接口信息改变如下所示：

组名为 mike 的文档中只有 user-controller 相关的接口信息

组名为 yank 的文档中只有 basic-error-controller 相关的接口信息

3. 控制 Swagger 的开启

4. 常用注解使用

@ApiModel

@ApiModelProperty

@ApiOperation

@ApiParam

5. 接口调用

三、进阶使用

1. 添加请求头