SpringBoot 精通系列-使用Swagger2构建RESTful APIs

快来打我* 2024-04-18 15:09 10阅读 0赞

> **导语**  
>   在之前的博客中曾经说过关于SpringBoot RESTful架构的知识，也提供了一个简单的小例子，当然在实际工作中更多的使用的是Swagger来实现一个RESTful的API。那么下面就来看看如何利用Swagger来构建一个RESTful APIs

### 文章目录 ###

*   *  什么是Swagger
     *  快速开发
     *   *   *  导入依赖POM文件
             *  创建SwaggerConfig的配置类
     *  Swagger 常用注解
     *   *  @Api
         *  @ApiOperation
         *  @ApiImplicitParams和@ApiImplicitParam的用法
         *  @ApiResponses 和@ApiResponse的使用
         *  @ApiModel 和 @ApiModelProperty的使用
     *  Try it out
     *  总结

## 什么是Swagger ##

Swagger是一个RESTfulAPI的工具，通过Swagger可以获取到项目的各种交互文档，以及客户端SKD的自动生效等功能。  
  Swagger的可以实现RESTful风格API的标准定义，与所用的开发语言无关，使用者和计算机是看不到源码或者是开发文档，或者说不能通过网络流量检测的情况下，可以发现和理解各种服务。当服务通过Swagger定义，消费者就能通过远程的服务调用来实现少部分的逻辑。类似于低级编程接口，Swagger去掉了服务调用的时候的猜测。实现了直接调用。是一个功能强大的API表达工具。  
  使用SpringBoot 来集成 Swagger，是要通过注解标记出需要在API中展示的信息，Swagger会根据项目中标记的注解来生成对应的API文档。Swagger是世界上最流行的API工具，提供了API的管理解决方案，API所需要的所有的要素在其中有所包含，也可以实现定制。

## 快速开发 ##

#### 导入依赖POM文件 ####

在开发之前首先需要解决的是SpringBoot如何集成Swagger2.x，需要在POM文件中导入如下的依赖。

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

#### 创建SwaggerConfig的配置类 ####

@Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
    
    }

在配置类上加上两个注解

*  @Configuration 表示这个类为一个配置类在启动的时候作为配置文件来使用
 *  @EnableSwagger2 表示这个项目启动了SwaggerAPI文档

在这个配置类中加入两个方法

@Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
    
        @Bean
        public Docket api(){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.nh"))
                    .paths(PathSelectors.any())
                    .build();
        }
        
        private ApiInfo apiInfo(){ 
            return new ApiInfoBuilder()
                    .title("用户管理")
                    .description("用户管理中心API 1.0 操作文档")
                    
                    .termsOfServiceUrl("http://www.nihui.com")
                    .version("1.0")
                    .contact(new Contact("倪辉开发","http://www.nihui.com","nihui@126.com"))
                    .build();
        }
    }

第一个方法使用了@Bean注解，就表示这个是要被注入到容器中的内容，返回的是一个Docket(Swagger API摘要)，这里需要注意的是其中需要指定需要扫描的包路径，也就是说在指定路径下的Controller类才会被生成SwaggerAPI文档。  
  第二个方法的配置相对比较重要点，主要包括了展示的主题、描述、版本、服务条款、服务联系方式等等。查看ApiInfo的源码会发现其实它还可以支持关键描述高亮处理。提供了如下的一些配置。

public class ApiInfo { 
      private final String version;
      private final String title;
      private final String description;
      private final String termsOfServiceUrl;
      private final String license;
      private final String licenseUrl;
      private final Contact contact;
      private final List<VendorExtension> vendorExtensions;

上面代码中显示的所有的信息都可以通过上面配置类中的方法进行配置。当然也可以使用默认值，配置完成之后就是启动项目查看是否配置成功。运行项目主启动类，并在浏览器中输入http://localhost:8080/swagger-ui.html 就会看到如下的内容，就说明配置有效。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70]  
  当然会看到在页面下方会出现\*\*No operations defined in spec!\*\*的字样，也就是说没有找到相关的API内容，这是因为还没有在对应的包下面添加Controller的信息，下面就来整合一下其他的代码看看效果如何。

## Swagger 常用注解 ##

在上面提到Swagger通过注解的方式来生成对应的文档，包括接口名、请求方法、请求参数、返回信息等等。其中常用的注解有以下一些。

<table> 
 <thead> 
  <tr> 
   <th>作用范围</th> 
   <th>API</th> 
   <th>使用位置</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>协议集描述</td> 
   <td>@Api</td> 
   <td>用于Controller类上</td> 
  </tr> 
  <tr> 
   <td>协议描述</td> 
   <td>@ApiOperation</td> 
   <td>用于在Controller的方法上</td> 
  </tr> 
  <tr> 
   <td>非对象参数集</td> 
   <td>@ApiImplicitParams</td> 
   <td>用在Controller的方法上</td> 
  </tr> 
  <tr> 
   <td>非对象参数描述</td> 
   <td>@ApiImplicitParam</td> 
   <td>用在被@ApiImplicitParams标注的方法里</td> 
  </tr> 
  <tr> 
   <td>响应集</td> 
   <td>@ApiResponses</td> 
   <td>用在Controller方法上</td> 
  </tr> 
  <tr> 
   <td>响应信息参数</td> 
   <td>@ApiResponse</td> 
   <td>用在@ApiResponses里面</td> 
  </tr> 
  <tr> 
   <td>描述返回对象的意义</td> 
   <td>@ApiModel</td> 
   <td>用在返回对象类上</td> 
  </tr> 
  <tr> 
   <td>对象属性</td> 
   <td>@APIModelProperty</td> 
   <td>使用在传入参数的对象字段上</td> 
  </tr> 
 </tbody> 
</table>

### @Api ###

首先来看一下@Api注解的作用

@Api(value = "用户",description = "用户操作API",position = 100,protocols = "http")
    @RestController
    public class UserController {

测试效果如下，自动将Controller中的所有方法都进行了映射。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70 1]

### @ApiOperation ###

ApiOperation是被标注在方法上，用来描述方法名、方法解释、方法返回信息、标记信息等等操作。

例如

@ApiOperation(
                value = "获取用户列表",
                notes = "获取所有用户信息",
                produces = "application/json,application/xml",
                consumes = "application/json,application/xml",
                response = List.class
        )
        @GetMapping("/allUser")
        public List<User> getAllUser(){ 
            return userService.getAllUser();
        }

**效果如下**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70 2]

### @ApiImplicitParams和@ApiImplicitParam的用法 ###

这两个注解用来描述方法的返回值信息，需要两个注解配合使用，@ApiImplicitParam注解重点描述的是每个参数的信息。例如

@ApiOperation(value = "增加用户操作",notes = "用户创建用户接口")
        @ApiImplicitParams({ 
                @ApiImplicitParam(name = "id",value = "用户ID",required = true,dataType = "Integer",paramType = "query"),
                @ApiImplicitParam(name = "name",value = "用户名",required = true,dataType = "String",paramType = "query"),
                @ApiImplicitParam(name = "password",value = "密码",required = true,dataType = "String",paramType = "query")
        })
        @PostMapping("/addUser")
        public int addUser(@RequestBody User user){ 
            return userService.addUser(user);
        }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70 3]

### @ApiResponses 和@ApiResponse的使用 ###

两者表示对于方法返回值的封装，@ApiResponse表示具体返回码以及返回信息的封装。

@ApiOperation(value = "获取用户信息",notes = "获取单个用户的信息")
        @ApiResponses({ 
                @ApiResponse(code=100,message = "请求参数有错"),
                @ApiResponse(code=101,message = "未授权"),
                @ApiResponse(code=103,message = "禁止访问"),
                @ApiResponse(code=104,message = "请求路径不存在"),
                @ApiResponse(code=105,message = "服务器内部错误"),
        })
        @GetMapping("/getOneUser")
        public User getUserById(@RequestParam Integer id){ 
            return userService.getUserById(id);
        }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70 4]

### @ApiModel 和 @ApiModelProperty的使用 ###

在实际项目中，通常会封装一个返回值对象，@ApiModel就是负责描述这个对象信息的。而@ApiModelProperty 是负责描述对象属性中的相关信息。这里我们拿实际生产上的一个例子做为说明

@JsonIgnoreProperties(ignoreUnknown = true)
    @Getter
    @Setter
    @ApiModel(description="响应对象")
    public class ResultResp<T> extends AbsJsonResp { 
    
    	private static final long serialVersionUID = 8262436911538688064L;
    	
    	@JsonProperty("date")
    	@ApiModelProperty(value="时间",name = "time")
    	private Date date=new Date();
    	/** * normal * error * exception */
    	@ApiModelProperty(value="响应状态",name = "状态")
    	@JsonProperty("status")
    	private String status="normal";
    	
    	@JsonProperty("exception")
    	private ExceptionMsg exceptionMsg;
    	
    	@ApiModelProperty(value="响应数据",name = "data")
    	@JsonProperty("response")
    	private T response;
    	
    	@JsonIgnore
    	public void setException(ParentException parentException){ 
    		this.exceptionMsg=parentException.getExceptionMsg();
    	}
    
    }

当然上面介绍的就是一些在实际开发中经常会用的注解，对于注解里面的具体有那些属性，可以自己研究。如果能够灵活的使用这些注解就可以构建出一个脉络清晰的API文档。

## Try it out ##

在上面截图中我们会看到一个Try it out 的按钮。Swagger在创建这个API的时候还提供了一个非常强大的功能，这个功能就是可以在接口页面上直接测试接口操作，这样如果是前端在调用后端系统出现问题的时候可以通过这页面进行测试。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70 5]

在点击完执行按钮之后会出现上面的效果。通过上面的结果截图可以看出实际上是调用了

> curl -X GET “http://localhost:8081/allUser” -H “accept: */*”

方式进行了测试调整后端的参数就可以看到这条命令的变化。

## 总结 ##

通过上次博客例子，演示了Swagger的使用，说明了Swagger是在实际开发中非常好用的一个组件。可以通过Swagger构建出非常丰富的API文档，也可以通过这个组件进行接口的测试。当然Swagger还有很多的功能等待大家的使用！

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/18/e4ba57d773084b148655a7d66c8e73df.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70 1]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/18/fedcf55e455f49b28924f1f0ca40d551.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70 2]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/18/996c44866cca4a20a492b7d42bc9be82.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70 3]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/18/fd05404729a8458c80162e87a0479563.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70 4]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/18/56b30303efe44aaa9055a1ce0a375fa9.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L25paHVpMTIz_size_16_color_FFFFFF_t_70 5]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/18/e5095da0e87546eba24dd64eb336fecd.png