swagger3 设置值可以为空_Swagger2常用注解说明

关注

原创最新推荐文章于 2026-06-23 21:42:13 发布 2.7k 阅读 AI 写同款· GEO 优化 ›

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/

javax.validation

validation-api

2.0.1.Final

com.github.xiaoymin

knife4j-spring-boot-starter

2.0.3

org.projectlombok

lombok

org.springframework.boot

spring-boot-starter-web

添加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 {

@Bean

public 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.youkuaiyun.com/", "thinkwon@163.com"))

// 服务网址

.termsOfServiceUrl("https://thinkwon.blog.youkuaiyun.com/")

// 版本

.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 list = new ArrayList<>();

@PostConstruct

private 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 list() {

return list;

}

@GetMapping("/page")

@ApiOperation(value = "分页查询用户列表")

@ApiImplicitParams({

@ApiImplicitParam(name = "pageNum", value = "当前页数"),

@ApiImplicitParam(name = "pageSize", value = "每页记录数")

})

public List 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 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 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删除用户

访问接口文档

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

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

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

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

Swagger2常用注解说明

Controller相关注解

@Api

用在请求的类上，表示对类的说明

注解属性

类型

描述

swagger3 设置值可以为空_Swagger2常用注解说明

相关推荐