Swagger-告别手写文档

文章目录

1. 引言
2. Swagger是什么？
3. SpringBoot2.7.3集成Swagger
4. 常见注解

1. 引言

在RESTful API开发中，维护准确、易读的接口文档是团队协作的核心挑战，通常接口文档分为离线的和实时的。离线的接口文档工具有 YAPI等，其中最大的弊端是接口程序发生变动时需要及时更新接口文档，十分麻烦。实时接口文档就是可以根据我们的代码来自动生成相应的接口文档，优点就是我们的代码发生变化时，生成的接口文档也会自动更新，无需我们关注修改，只需要按时发布即可。但是由于是根据代码自动生成的，所以最大的弊端就是代码侵入性强，需要我们在项目代码中集成生成接口文档的相关代码。实时接口文档现在的方案有很多，但是Swagger还是其中比较有影响力的一个。

2. Swagger是什么？

Swagger是一套基于OpenAPI规范的工具生态，通过自动化生成交互式文档和测试工具，解决了API设计、调试与协作的痛点，其核心价值是定义即文档，文档即测试。包含：

Swagger Editor：可视化编写API定义的编辑器。
Swagger UI：一个无依赖的HTML、JS和CSS集合，自动生成可交互的API文档页面。
Swagger Codegen：个模板驱动引擎，根据API定义生成客户端/服务端代码。

3. SpringBoot2.7.3集成Swagger

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，基于Swagger的国产开源工具，提供更强大的API文档界面和功能扩展，目前，一般都使用knife4j框架。其核心优势如下：
1. 更美观的UI界面，支持Markdown文档补充。
2. 动态调试参数、离线文档导出（PDF/Word）。
3. 接口权限控制、全局参数配置等企业级功能。

添加依赖：

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.3</version>
</dependency>

配置Swagger基本信息：

@Configuration
public class Knife4jConfig {@Beanpublic Docket docket(Environment environment) {// 设置环境范围Profiles profiles = Profiles.of("dev","test");// 如果在该环境返回内则返回：true，反之返回 falseboolean flag = environment.acceptsProfiles(profiles);Docket docket = new Docket(DocumentationType.SWAGGER_2).enable(flag).apiInfo(getApiInfo()).select() //设置扫描接口.apis(RequestHandlerSelectors//.any() // 扫描全部的接口，默认//.none() // 全部不扫描//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口.basePackage("com.clx.controller"))//扫描指定包下的接口，最为常用.paths(PathSelectors.any()) //满足条件的路径，该断言总为true//.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）//.ant("/user/**") // 满足字符串表达式路径//.regex("") // 符合正则的路径.build();return docket;}//文档相关信息private ApiInfo getApiInfo() {return new ApiInfoBuilder().title("宠物项目测试标题").description("宠物项目测试接口文档").version("1.0").contact(new Contact("芝士小霸王龙", "https://example.com", "contact@example.com")).build();}protected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}

当SpringBoot版本过高时需要在application.yml中配置如下信息：

server:port: 8080
spring:profiles:active:	dev #建议在开发环境中使用mvc:pathmatch:matching-strategy: ANT_PATH_MATCHER

访问http://localhost:8080/doc.html访问接口文档。

在这里插入图片描述

4. 常见注解

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，以下是对 Swagger2（springfox） 和 Swagger3（OpenAPI 3.0，springdoc） 常用注解的对比：

功能	Swagger2（springfox）	Swagger3（springdoc-openapi）
文档入口注解	`@EnableSwagger2`	`@OpenAPIDefinition`
接口分组/分类	`@Api(tags = "用户模块")`	`@Tag(name = "用户模块")`
接口方法描述	`@ApiOperation("查询用户")`	`@Operation(summary = "查询用户")`
参数描述	`@ApiParam("用户ID")`	`@Parameter(description = "用户ID")`
响应模型定义	`@ApiResponse(code=200, message="成功")`	`@ApiResponse(responseCode="200", description="成功")`
实体类字段说明	`@ApiModelProperty("用户名")`	`@Schema(description = "用户名")`
隐藏接口/类	`@ApiIgnore`	`@Hidden`
安全认证配置	无直接注解（需配置`SecurityScheme`类）	`@SecurityScheme`（支持OAuth2、JWT等

常用注解示例：

接口类定义：

@Api(tags = "用户管理")
@RestController
public class UserController {}@Tag(name = "用户管理")
@RestController
public class UserController {}

接口方法描述：

@ApiOperation(value = "创建用户", notes = "需提供用户名和密码")
@PostMapping("/user")
public User createUser(@ApiParam("用户对象") @RequestBody User user) {}@Operation(summary = "创建用户", description = "需提供用户名和密码")
@PostMapping("/user")
public User createUser(@Parameter(description = "用户对象") @RequestBody User user) {}

实体类字段说明：

@ApiModel("用户实体")
public class User {@ApiModelProperty(value = "用户ID", example = "1001")private Long id;
}@Schema(name = "用户实体")
public class User {@Schema(description = "用户ID", example = "1001")private Long id;
}