一篇文章带你搞定 SpringBoot 整合 Swagger2

Bertha 。 2022-12-17 10:59 268阅读 0赞

前后端分离后，维护接口文档基本上是必不可少的工作。  
一个理想的状态是设计好后，接口文档发给前端和后端，大伙按照既定的规则各自开发，开发好了对接上了就可以上线了。当然这是一种非常理想的状态，实际开发中却很少遇到这样的情况，接口总是在不断的变化之中，有变化就要去维护，做过的小伙伴都知道这件事有多么头大！还好，有一些工具可以减轻我们的工作量，Swagger2就是其中之一，至于其他类似功能但是却收费的软件，这里就不做过多介绍了。

### 文章目录 ###

*   *  一、创建工程
     *  二、Swagger2 配置
     *  三、简单示例
     *  四、中文配置案例
     *  五、在 Security 中的配置

## 一、创建工程 ##

创建 SpringBoot 工程项目，创建时只需要加入 `spring-boot-starter-web` 依赖即可，  
[Maven 仓库搜索 Swagger2 依赖：][Maven _ Swagger2]

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 1]

<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>

## 二、Swagger2 配置 ##

Swagger2的配置也是比较容易的，在项目创建成功之后，只需要开发者自己提供一个Docket的Bean即可，如下：

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2WebFlux;
    
    @Configuration
    @EnableSwagger2
    public class Swagger2Config { 
        @Bean
        Docket docket() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("org.yolo.swagger2.controller"))
                    .paths(PathSelectors.any())
                    .build().apiInfo(new ApiInfoBuilder()
                            //网站描述
                            .description("接口文档的描述信息")
                            .title("微人事项目接口文档")
                            //联系人信息
                            .contact(new Contact("yolo","blog.csdn.net","xxxx@gmail.com"))
                            //版本
                            .version("v1.0")
                            .license("Apache2.0")
                            .build());
        }
    }

这里提供一个配置类，首先通过`@EnableSwagger2WebFlux`注解启用`Swagger2`，然后配置一个Docket Bean，这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等。

## 三、简单示例 ##

（1）定义 User

public class User { 
        private Integer id;
        private String username;
        private String address;
        //get,set 方法省略
    }

（2）定义 Controller

@RestController
    public class UserController { 
        @GetMapping("/user")
        public User getUserById(Integer id){ 
            User user = new User();
            user.setId(id);
            return user;
        }
    }

在这种 restful 风格的代码里，需要明确指定接口是什么请求（get/post 等），不能直接写成 `requestMapping`，不然前端会生成6个方法，get，post 等都能发，会比较混乱。

启动项目，访问：http://localhost:8080/swagger-ui.html

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 2]  
也可以配置成中文描述

## 四、中文配置案例 ##

（1）对于参数的描述可以放在实体类中

@ApiModel(value = "用户实体类",description = "用户信息描述类")
    public class User { 
        @ApiModelProperty(value = "用户id")
        private Integer id;
        @ApiModelProperty(value = "用户名")
        private String username;
        @ApiModelProperty(value = "用户地址")
        private String address;
    	//get,set 方法省略
    }

（2）创建接口

@RestController
    @Api(tags = "用户数据接口")
    public class UserController { 
        @ApiOperation(value = "查询用户", notes = "根据用户id查询用户")
        @ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99")
        @GetMapping("/user")
        public User getUserById(Integer id) { 
            User user = new User();
            user.setId(id);
            return user;
        }
    
        @ApiOperation(value = "删除用户", notes = "根据用户id删除用户")
        @ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99")
        @ApiResponses({ 
                @ApiResponse(code = 200, message = "删除成功"),
                @ApiResponse(code = 500, message = "删除失败")
        })
        @DeleteMapping("/user/{id}")
        public void deleteUserById(@PathVariable Integer id) { 
            System.out.println("deleteUserById:" + id);
        }
    
        @PutMapping("/user")
        @ApiImplicitParams({ 
                @ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99"),
                @ApiImplicitParam(name = "username", value = "用户名", required = true, defaultValue = "javaboy")
        })
        @ApiOperation(value = "更新用户", notes = "根据用户id更新用户名")
    // @ApiIgnore
        public User updateUsernameById(String username, Integer id) { 
            User user = new User();
            user.setId(id);
            user.setUsername(username);
            return user;
        }
    
        @PostMapping("/user")
        @ApiOperation(value = "添加用户", notes = "添加用户接口")
        public User addUser(@RequestBody User user) { 
            return user;
        }
    }

> （1）`@Api`注解可以用来标记当前`Controller`的功能。  
> （2）`@ApiOperation`注解用来标记一个方法的作用。  
> （3）`@ApiImplicitParam`注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。  
> （4）如果有多个参数，则需要使用多个`@ApiImplicitParam`注解来描述，多个`@ApiImplicitParam`注解需要放在一个`@ApiImplicitParams`注解中。  
> （5）需要注意的是，`@ApiImplicitParam`注解中虽然可以指定参数是必填的，但是却不能代替`@RequestParam(required = true)`，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，`@RequestParam(required = true)`注解还是不能省略。

（3）效果展示

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 3]  
可以看到，所有的接口这里都列出来了，包括接口请求方式，接口地址以及接口的名字等，点开一个接口，可以看到如下信息：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 4]  
可以看到，接口的参数，参数要求，参数默认值等等统统都展示出来了，参数类型下的`query`表示参数以`key/value`的形式传递，点击右上角的`Try it out`，就可以进行接口测试：

点击Execute按钮，表示发送请求进行测试。测试结果会展示在下面的Response中。

小伙伴们注意，参数类型下面的`query`表示参数以`key/value`的形式传递，这里的值也可能是`body`，`body`表示参数以请求体的方式传递，例如上文的更新接口，如下：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 5]  
当然还有一种可能就是这里的参数为path，表示参数放在路径中传递，例如根据id查询用户的接口：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 6]

## 五、在 Security 中的配置 ##

如果我们的Spring Boot项目中集成了Spring Security，那么如果不做额外配置，Swagger2文档可能会被拦截，此时只需要在Spring Security的配置类中重写configure方法，添加如下过滤即可：

@Override
    public void configure(WebSecurity web) throws Exception { 
        web.ignoring()
                .antMatchers("/swagger-ui.html")
                .antMatchers("/v2/**")
                .antMatchers("/swagger-resources/**");
    }

如此之后，Swagger2文件就不需要认证就能访问了。

[Maven _ Swagger2]: https://mvnrepository.com/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center]: /images/20221122/8b85bbb761e54e3cbf7b847446e92a6b.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221122/60afc28ea70b4072a210ee375b06d2b9.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20221122/76d476b3793b4ed6bfc1e82ff733b7b6.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 3]: /images/20221122/00c9c62adc0d43919efecc3b69544eb0.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 4]: /images/20221122/a9e19d1445274ab78c35854e8c7dcb21.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 5]: /images/20221122/055e3076510042748d4b65fec1c58891.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25hbmh1YWliZWlhbg_size_16_color_FFFFFF_t_70_pic_center 6]: /images/20221122/d0d60c02fcb04b7da3fdd76c47484c81.png