Springboot集成SwaggerUI

小咪咪 2023-06-25 04:57 4阅读 0赞

# Springboot集成SwaggerUI #

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。  
作用：

*  接口的文档在线自动生成。
 *  功能测试。

## 工程创建 ##

<dependency>
       <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.8.0</version>
    </dependency>
    
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.8.0</version>
    </dependency>

## Swagger2配置 ##

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

@Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket api() {
     
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    // 自行修改为自己的包路径
                    .apis(RequestHandlerSelectors.basePackage("com.bj.demo"))
                    .paths(PathSelectors.any())
                    .build();
        }
        //构建API文档的详细信息函数
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //页面标题
    				.title("Spring Boot 测试使用 Swagger2 构建RESTful API")
    				//创建人
    				.contact(new Contact("zss", "http://www.baidu.com", ""))
    				//版本号
    				.version("1.0")
    				//描述
    				.description("API 描述")
    				.build();
        }
    }

用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。  
@EnableSwagger2 也可以在 Application.class 加上注解，表示开启Swagger2。

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

此时启动项目，输入http://localhost:8080/swagger-ui.html，能够看到如下页面，说明已经配置成功了：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ_size_16_color_FFFFFF_t_70]

## 创建接口 ##

@RestController
    @Api(tags = "用户管理相关接口")
    @RequestMapping("/user")
    public class UserController {
    
        @PostMapping("/")
        @ApiOperation("添加用户的接口")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),
                @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "深圳", required = true)
        }
        )
        public RespBean addUser(String username, @RequestParam(required = true) String address) {
            return new RespBean();
        }
    
        @GetMapping("/")
        @ApiOperation("根据id查询用户的接口")
        @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99", required = true)
        public User getUserById(@PathVariable Integer id) {
            User user = new User();
            user.setId(id);
            return user;
        }
        @PutMapping("/{id}")
        @ApiOperation("根据id更新用户的接口")
        public User updateUserById(@RequestBody User user) {
            return user;
        }
    }

### Swagger注解 ###

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

*  @Api：修饰整个类，描述Controller的作用
 *  @ApiOperation：描述一个类的一个方法，或者说一个接口
 *  @ApiParam：单个参数描述
 *  @ApiModel：用对象来接收参数
 *  @ApiProperty：用对象接收参数时，描述对象的一个字段
 *  @ApiResponse：HTTP响应其中1个描述
 *  @ApiResponses：HTTP响应整体描述
 *  @ApiIgnore：使用该注解忽略这个API
 *  @ApiError ：发生错误返回的信息
 *  @ApiImplicitParam：一个请求参数
 *  @ApiImplicitParams：多个请求参数

接下来测试一下接口：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ_size_16_color_FFFFFF_t_70 1]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ_size_16_color_FFFFFF_t_70 2]

## 后记 ##

### 使用lombok ###

\*\* lombok简介\*\*  
Lombok想要解决了的是在我们实体Bean中大量的Getter/Setter方法，以及toString, hashCode等可能不会用到，但是某些时候仍然需要复写，以期方便使用的方法；在使用Lombok之后，将由其来自动帮你实现代码生成，注意，其是 在运行过程中，帮你自动生成的 。就是说，将极大减少你的代码总量。

lombok作用  
消除模板代码：getter、setter、构造器、toString()、equals()  
便捷的生成比较复杂的代码，例如一个POJO要转化成构建器模式的形式，只需要一个注解。

idea中，File–>settings–>Plugins–>输入lo 按安装Lombok  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ_size_16_color_FFFFFF_t_70 3]  
pom.xml引用方式：

<dependency>
    	<groupId>org.projectlombok</groupId>
      	<artifactId>lombok</artifactId>
      	<optional>true</optional>
    </dependency>

MAVEN引用

<dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.10</version>
        <scope>provided</scope>
    </dependency>

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20191226110347956.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20191226111353897.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/201912261114439.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20191226112008368.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl8zODQwOTkxNQ==,size_16,color_FFFFFF,t_70