Swagger-的使用 +Swagger-UI添加请求头

逃离我推掉我的手 2023-09-26 23:18 55阅读 0赞

#### 文章目录 ####

*  前言
 *  一、简介
 *  二、基本使用
 *   *  1. 导入相关依赖
     *  2. 编写配置文件
     *   *  2.1 配置基本信息
         *  2.2 配置接口信息
         *  2.3 配置分组信息
     *  3. 控制 Swagger 的开启
     *  4. 常用注解使用
     *   *  @ApiModel
         *  @ApiModelProperty
         *  @ApiOperation
         *  @ApiParam
     *  5. 接口调用
 *  三、进阶使用
 *   *  1. 添加请求头
    
    --------------------
    
    ## 前言 ##
    
    作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。[Swagger][] 可以较好的接口接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。
    
    ## 一、简介 ##
    
    官网：[https://swagger.io/][https_swagger.io]
    
    Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
    
    Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
    
    **Swagger 的优势**
    
     *  支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
     *  提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
    
    ## 二、基本使用 ##
    
    ### 1. 导入相关依赖 ###
    
    通过在项目中引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。
    
        
                <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 文档。

![在这里插入图片描述][d965c0a0bcdd478a99cef5a82738b2ed.png]  
可以看到 Swagger 文档中大概有这四类信息

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

#### 2.1 配置基本信息 ####

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

Swagger 默认的基本信息展示

![在这里插入图片描述][8ecd7b81fbdb4125b0a1f1532a61349d.png]

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://blog.csdn.net/xhmico?type=blog", // 作者网址
                    "777777777@163.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 文档，基本信息改变如下所示：

![在这里插入图片描述][8a23ffe7863e4c58bf538b61ab37de2d.png]

#### 2.2 配置接口信息 ####

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

![在这里插入图片描述][b8f8a6b7a9e54659820599aea8ce4070.png]

有时候我们希望不要展示 `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 文档，接口信息改变如下所示：

![在这里插入图片描述][454edf96b40a490088cf41f0cc316a41.png]

可以看到之前 `basic-error-controller` 相关的接口已经没有了

#### 2.3 配置分组信息 ####

Swagger 默认只有一个 default 分组选项，如果没有设置，所有的接口都会显示在 `default` 分组下，如果功能模块和接口数量一多，就会显得比较凌乱，不方便查找和使用。

swagger 文档中组名默认是 `default`，可通过 `.groupName(String )`

![在这里插入图片描述][874aea5c6d794599a459e434be8e9134.png]

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

修改后：  
![在这里插入图片描述][06b5cc26f2c24fb691f275e69bd96f27.png]  
如果需要配置多个组的话，就需要配置多个 `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` 相关的接口信息

![在这里插入图片描述][c87eb2d8a25943b1b29645b1c2fcdc83.png]

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

![在这里插入图片描述][00b106b8bc2d42f5a636843aab01fb2e.png]

--------------------

### 3. 控制 Swagger 的开启 ###

在开发或者测试环境下，我们开启 swagger 会方便前端和后端的交互，但是如果在生产环境下也开启 swagger 的话，是会将接口暴露出去的，有极大风险，如何让 swagger 根据不同的环境来决定是否开启？

这里我准备了四个项目的配置文件，`dev`、`test`、`pro` 三个环境的配置文件仅是端口上的不同

![在这里插入图片描述][6b7c4a2fabbc498ba3cbea4d3d6b2c47.png]

*  application.yml -------------------------- 全局配置文件
 *  application-dev.yml -------------------- 开发环境配置文件
 *  application-test.yml -------------------- 测试环境配置文件
 *  application-pro.yml -------------------- 生产环境配置文件

`application.yml` 内容如下，用于指定选择的环境：

spring:
      profiles:
        active: dev

可以通过代码判断此时是在什么环境：`dev`、`test`、`pro`，如果是在 `pro` 生产环境，则关闭 swagger。

/**
         * swagger 配置
         * @param environment 环境
         */
        @Bean
        public Docket docket(Environment environment) {
        
    
            // 设置环境范围
            Profiles profiles = Profiles.of("dev","test");
            // 如果在该环境返回内则返回：true，反之返回 false
            boolean flag = environment.acceptsProfiles(profiles);
    
            // 创建一个 swagger 的 bean 实例
            return new Docket(DocumentationType.SWAGGER_2)
                    .enable(flag) // 是否开启 swagger：true -> 开启，false -> 关闭
                    ;
        }

在 `application.yml` 全局配置文件中环境指向 `dev` 时，是可以打开 swagger 的

![在这里插入图片描述][43a6b878984d4ba2b8a9d903a7103eef.png]  
如果我将 `application.yml` 全局配置文件中环境指向 `pro` 时，就不能打开 swagger 了，提示 `Could not render e, see the console`

![在这里插入图片描述][138b1db9041d4f0a949dd3c95e956920.png]

### 4. 常用注解使用 ###

之前有说 Swagger 会将接口请求或者相应的实体类信息展示在 `Models` 下的，比如我 `UserController.java` 下有一个接口如下所示：

@PostMapping(value = "/query-user-info")
        public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) {
        
            return ResponseBean.success(userService.queryUserInfo(req));
        }

它的请求体是 `IdReq`，响应是 `ResponseBean`，`Models` 展示这两个实体类信息如下：

![在这里插入图片描述][6befd4da7498411d89220e9548aafd24.png]  
前端可通过看这个 `Models` 知道后端定义实体类的信息。

#### @[ApiModel][] ####

该注解是作用于实体类上面的，是用来描述实体类的一些基本信息的。

相关属性：

*  name：参数名
 *  value：参数说明
 *  required：是否必填

这里我以 `UserController` 下的接口为例：

@PostMapping(value = "/query-user-infos")
        @ApiOperation(value = "条件查询用户信息")
        public ResponseBean queryUserInfos(
                // name 用户名称 不必填
                @ApiParam(value = "用户名称", required = false) @RequestParam(required = false) String name,
                // gender 用户性别 必填
                @ApiParam(value = "用户性别", required = true) @RequestParam(required = true) GenderEnum gender
        ) {
        
            return ResponseBean.success(userService.queryUserInfos(name,gender));
        }

![在这里插入图片描述][82fae1a1b8514588ac83d102fab39f25.png]  
这里会展示请求参数的备注信息，以及是否必填等。

### 5. 接口调用 ###

使用 swagger 除了让前后端交互变得方便，也让接口的请求变得简单，只需要填写好请求所需要的参数信息，便可直接发起请求。

比如说接口 `/user/query-user-info`

点击 `Try it out`

![在这里插入图片描述][e96bf4ae28814856bbb9855d991bfe1a.png]  
设置好请求所需的参数，点击 `Execute` 执行

![在这里插入图片描述][5b57eef70c8c4d4a846cea69d82bc776.png]

就能看到接口响应的结果了

![在这里插入图片描述][051779175e5f4199b7dcc5e222a261e6.png]

接口 `/user/query-user-infos` 也差不多

![在这里插入图片描述][e33756b5d1b54782aca530babf3822cc.png]  
![在这里插入图片描述][a013f81a6dd64994909bd4c16c31063d.png]

--------------------

## 三、进阶使用 ##

### 1. 添加请求头 ###

有时候我们的接口是需要获取请求头信息的，这样的话就还需要在 swagger 配置中添加请求头的配置。

@Bean
        public Docket docket() {
        
            // 设置请求头
            List<Parameter> parameters = new ArrayList<>();
            parameters.add(new ParameterBuilder()
                    .name("token") // 字段名
                    .description("token") // 描述
                    .modelRef(new ModelRef("string")) // 数据类型
                    .parameterType("header") // 参数类型
                    .defaultValue("default value") // 默认值：可自己设置
                    .hidden(true) // 是否隐藏
                    .required(false) // 是否必须
                    .build());
    
            // 创建一个 swagger 的 bean 实例
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("mike") // 修改组名为 "mike"
                    // 配置接口信息
                    .select() // 设置扫描接口
                    // 配置如何扫描接口
                    .apis(RequestHandlerSelectors
                            .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
                    )
                    .paths(PathSelectors
                            .any() // 满足条件的路径，该断言总为true
                    )
                    .build()
    
                    // 添加请求头参数
                    .globalOperationParameters(parameters);
        }

比如接口：

@GetMapping(value = "/get-token")
        @ApiOperation(value = "获取请求头中的token信息")
        public void getToken(
                @RequestHeader(value = "token",required = false) String token
        ) {
        
            // 直接获取 token 信息
            System.out.println("token = " + token);
    
            // 通过代码获取
            ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
            if (servletRequestAttributes != null) {
        
                HttpServletRequest request = servletRequestAttributes.getRequest();
                String header = request.getHeader("token");
                System.err.println("header = " + header);
            }
        }

![在这里插入图片描述][ba3332f9c2124c519d1e827b50b8d13a.png]  
可以看到这个接口已经可以去设置请求头了，调用接口

![在这里插入图片描述][0c485d2e5c3541eb9e63c8d87639e911.png]  
后端也能获取到。

##   ##

[Swagger]: https://so.csdn.net/so/search?q=Swagger&spm=1001.2101.3001.7020
[https_swagger.io]: https://swagger.io/
[d965c0a0bcdd478a99cef5a82738b2ed.png]: https://img-blog.csdnimg.cn/d965c0a0bcdd478a99cef5a82738b2ed.png
[8ecd7b81fbdb4125b0a1f1532a61349d.png]: https://img-blog.csdnimg.cn/8ecd7b81fbdb4125b0a1f1532a61349d.png
[8a23ffe7863e4c58bf538b61ab37de2d.png]: https://img-blog.csdnimg.cn/8a23ffe7863e4c58bf538b61ab37de2d.png
[b8f8a6b7a9e54659820599aea8ce4070.png]: https://img-blog.csdnimg.cn/b8f8a6b7a9e54659820599aea8ce4070.png
[454edf96b40a490088cf41f0cc316a41.png]: https://img-blog.csdnimg.cn/454edf96b40a490088cf41f0cc316a41.png
[874aea5c6d794599a459e434be8e9134.png]: https://img-blog.csdnimg.cn/874aea5c6d794599a459e434be8e9134.png
[06b5cc26f2c24fb691f275e69bd96f27.png]: https://img-blog.csdnimg.cn/06b5cc26f2c24fb691f275e69bd96f27.png
[c87eb2d8a25943b1b29645b1c2fcdc83.png]: https://img-blog.csdnimg.cn/c87eb2d8a25943b1b29645b1c2fcdc83.png
[00b106b8bc2d42f5a636843aab01fb2e.png]: https://img-blog.csdnimg.cn/00b106b8bc2d42f5a636843aab01fb2e.png
[6b7c4a2fabbc498ba3cbea4d3d6b2c47.png]: https://img-blog.csdnimg.cn/6b7c4a2fabbc498ba3cbea4d3d6b2c47.png
[43a6b878984d4ba2b8a9d903a7103eef.png]: https://img-blog.csdnimg.cn/43a6b878984d4ba2b8a9d903a7103eef.png
[138b1db9041d4f0a949dd3c95e956920.png]: https://img-blog.csdnimg.cn/138b1db9041d4f0a949dd3c95e956920.png
[6befd4da7498411d89220e9548aafd24.png]: https://img-blog.csdnimg.cn/6befd4da7498411d89220e9548aafd24.png
[ApiModel]: https://so.csdn.net/so/search?q=ApiModel&spm=1001.2101.3001.7020
[de46611c80f141bc82dae4535abfab70.png]: https://img-blog.csdnimg.cn/de46611c80f141bc82dae4535abfab70.png
[ApiModelProperty]: https://so.csdn.net/so/search?q=ApiModelProperty&spm=1001.2101.3001.7020
[ApiModelProperty 1]: https://blog.csdn.net/weixin_44356055/article/details/109451892
[8568c00c30cb44c4ab523fafd2b16ae7.png]: https://img-blog.csdnimg.cn/8568c00c30cb44c4ab523fafd2b16ae7.png
[Swagger _ApiOperation]: https://www.hxstrive.com/article/959.htm
[129a4c5d520e453da1c4790d64a8b207.png]: https://img-blog.csdnimg.cn/129a4c5d520e453da1c4790d64a8b207.png
[82fae1a1b8514588ac83d102fab39f25.png]: https://img-blog.csdnimg.cn/82fae1a1b8514588ac83d102fab39f25.png
[e96bf4ae28814856bbb9855d991bfe1a.png]: https://img-blog.csdnimg.cn/e96bf4ae28814856bbb9855d991bfe1a.png
[5b57eef70c8c4d4a846cea69d82bc776.png]: https://img-blog.csdnimg.cn/5b57eef70c8c4d4a846cea69d82bc776.png
[051779175e5f4199b7dcc5e222a261e6.png]: https://img-blog.csdnimg.cn/051779175e5f4199b7dcc5e222a261e6.png
[e33756b5d1b54782aca530babf3822cc.png]: https://img-blog.csdnimg.cn/e33756b5d1b54782aca530babf3822cc.png
[a013f81a6dd64994909bd4c16c31063d.png]: https://img-blog.csdnimg.cn/a013f81a6dd64994909bd4c16c31063d.png
[ba3332f9c2124c519d1e827b50b8d13a.png]: https://img-blog.csdnimg.cn/ba3332f9c2124c519d1e827b50b8d13a.png
[0c485d2e5c3541eb9e63c8d87639e911.png]: https://img-blog.csdnimg.cn/0c485d2e5c3541eb9e63c8d87639e911.png