Swagger2常用注解说明

文章目录

Swagger2简介
使用Swagger解决的问题
Spring Boot集成Swagger2
- 添加依赖
- 添加Swagger2Config配置类
- 编写接口
- - 用户DTO
  - 用户controller
- 访问接口文档
Swagger2常用注解说明
- Controller相关注解
- - @Api
- 接口相关注解
- - @ApiOperation
  - @ApiParam
  - @ApiImplicitParams
  - @ApiImplicitParam
  - @ApiResponses
  - @ApiResponse
- Model相关注解
- - @ApiModel
  - @ApiModelProperty

Swagger2简介

swagger官网对 swagger 的描述如下：

Swagger takes the manual work out of API documentation, with a range of solutions for generating, visualizing, and maintaining API docs.

Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset.

Swagger提供了用于生成，可视化和维护API文档的一系列解决方案，从而使API文档不再需要人工操作。

借助Swagger开源和专业工具集，为用户，团队和企业简化API开发。

我的总结：Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、使用和测试 Rest API。

使用Swagger解决的问题

现在大部分公司都采用前后端分离开发的模式，前端和后端工程师各司其职。这就要求有一份及时更新且完整的Rest API 文档来提高工作效率。Swagger 解决的问题主要有以下三点：

保证文档的时效性：只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，代码变文档跟着变
接口请求参数和返回结果不明确的问题
在线测试接口

Spring Boot集成Swagger2

这里通过构建一个简单的Spring Boot项目，并使用Swagger注解，来演示如何使用Swagger

添加依赖

这里没有添加springfox-swagger2和springfox-swagger2-ui依赖，而是使用knife4j-spring-boot-starter依赖，官网地址：https://doc.xiaominfo.com/knife4j/

<!-- 一些校验的依赖，不然启动会报NoClassDefFoundError: javax/validation/constraints/Min -->
<dependency><groupId>javax.validation</groupId><artifactId>validation-api</artifactId><version>2.0.1.Final</version>
</dependency><!-- Spring Boot单服务架构使用最新版的knife4j依赖，已经继承swagger依赖，同时增强UI实现 -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.3</version>
</dependency><!-- lombok依赖 -->
<dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId>
</dependency><!-- spring-boot-starter-web依赖 -->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId>
</dependency>

添加Swagger2Config配置类

注意：RequestHandlerSelectors.basePackage("com.jourwon.springboot.knife4j.controller") 为 Controller 包路径，不然生成的文档扫描不到接口，也可以使用RequestHandlerSelectors.any()配置

/*** Swagger2配置类** @author JourWon* @date 2020/6/1*/
@EnableKnife4j
@EnableSwagger2
@Configuration
@Import(value = {BeanValidatorPluginsConfiguration.class})
public class Swagger2Config {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder()// 标题.title("我的Swagger API文档")// 描述.description("使用Knife4j构建API文档")// 作者信息.contact(new Contact("ThinkWon", "https://thinkwon.blog.csdn.net/", "thinkwon@163.com"))// 服务网址.termsOfServiceUrl("https://thinkwon.blog.csdn.net/")// 版本.version("1.0.0").build();}}

编写接口

用户DTO

/*** 用户** @author JourWon* @date 2020/6/1*/
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户", description = "查询用户")
public class UserDTO implements Serializable {private static final long serialVersionUID = 78806598597025327L;@ApiModelProperty(value = "用户id")private Integer userId;@ApiModelProperty(value = "用户名")private String username;}

用户controller


/*** 用户controller** @author JourWon* @date 2020/6/1*/
@RestController
@RequestMapping(value = {"/user"})
@Api(tags = {"用户controller"})
public class UserController {private List<UserDTO> list = new ArrayList<>();@PostConstructprivate void post() {list.add(new UserDTO(1, "JourWon"));list.add(new UserDTO(2, "Jobs"));list.add(new UserDTO(3, "JackMa"));}@GetMapping("/list")@ApiOperation(value = "查询用户列表")public List<UserDTO> list() {return list;}@GetMapping("/page")@ApiOperation(value = "分页查询用户列表")@ApiImplicitParams({@ApiImplicitParam(name = "pageNum", value = "当前页数"),@ApiImplicitParam(name = "pageSize", value = "每页记录数")})public List<UserDTO> page(@RequestParam(defaultValue = "1", required = false) Integer pageNum, @RequestParam(defaultValue = "10", required = false) Integer pageSize) {return list;}@GetMapping("/{userId}")@ApiOperation(value = "根据用户id查询用户")public UserDTO get(@PathVariable("userId") Integer userId) {for (UserDTO userDTO : list) {if (userDTO.getUserId().equals(userId)) {return userDTO;}}return new UserDTO();}@PostMapping@ApiOperation(value = "新增用户")public Boolean insert(@RequestBody @ApiParam(name = "UserDTO", value = "新增用户参数") UserDTO userDTO) {list.add(userDTO);return true;}@DeleteMapping("/{userId}")@ApiOperation(value = "根据用户id删除用户")public Boolean delete(@PathVariable("userId") Integer userId) {Iterator<UserDTO> iterator = list.iterator();while (iterator.hasNext()) {if (iterator.next().getUserId().equals(userId)) {iterator.remove();return true;}}return false;}@PutMapping@ApiOperation(value = "更新用户信息")@ApiResponses({@ApiResponse(code = 400, message = "请求参数没填好"),@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")})public Boolean update(@RequestBody @ApiParam(name = "UserDTO", value = "更新用户参数") UserDTO userDTO) {Iterator<UserDTO> iterator = list.iterator();while (iterator.hasNext()) {UserDTO next = iterator.next();if (next.getUserId().equals(userDTO.getUserId())) {next.setUsername(userDTO.getUsername());return true;}}return false;}}

这个controller有了六个接口，分别是:

/user/list，get请求方式：查询用户列表
/user/page，get请求方式：分页查询用户列表
/user/{userId}，get请求方式：根据用户id查询用户
/user，post请求方式：新增用户
/user，put请求方式：更新用户信息
/user/{userId}，delete请求方式：根据用户id删除用户

访问接口文档

启动一下项目，然后在浏览器中访问 http://localhost:8080/doc.html

主页展示API文档基本信息，包括简介，作者，版本等信息

同时可以看到用户controller的所有接口

这里我们调试以下查询用户列表的接口

至此，Spring Boot集成Swagger2，构建API文档已经完成