Swagger annotations 如何使用？详解 Swagger 注解

Swagger Annotations 是 Swagger 框架提供的一组用于描述和定义 API 文档的注解。这些注解通过标识代码中的相关部分，让 Swagger 能够解析并生成 API 文档。Swagger annotations 能够将开发人员的注解转化为一个可视化的 API 文档，包括 API 的路径、参数、响应等细节信息。这使得开发人员能够更好地理解和沟通 API 的功能和用法，同时也方便了测试和集成。

Swagger annotations 使用场景

使用 Swagger annotations 在以下情况下是有意义的：

在开发阶段，用于定义和记录 API 的细节。开发人员可以通过注解清楚地指定 API 的请求和响应等相关信息，使得其他开发人员能够更好地理解和使用 API。
在文档生成和展示方面，Swagger annotations 可以自动生成和展示 API 文档，包括请求和响应的结构、参数、示例等。这方便了其他人员在使用和测试 API 时的参考。
在 API 测试方面，Swagger annotations 可以与自动化测试工具集成，使得测试人员可以使用注解生成测试用例，快速进行 API 的集成测试。

Swagger annotations 用法介绍

使用 Swagger annotations 需要将相关的注解添加到 API 的代码中。以下是一些常用的 Swagger 注解：

@Api：用于描述整个 API 的信息，包括 API 的名称、描述、标签等。
@ApiOperation：用于描述一个 API 操作的信息，包括操作的名称、描述、HTTP 方法等。
@ApiParam：用于描述请求参数的信息，包括参数的名称、描述、数据类型、默认值等。
@ApiResponse：用于描述 API 操作的响应信息，包括响应的 HTTP 状态码、描述、响应的数据类型等。
@ApiModel：用于描述一个数据模型，包括模型的名称、描述、属性等。
@ApiModelProperty：用于描述模型的一个属性，包括属性的名称、描述、数据类型等。
@ApiIgnore：用于忽略某个 API 或 API 操作，让 Swagger 不会生成相应的文档。
通过使用这些注解，开发人员可以在代码中添加相关的描述和信息，并通过 Swagger 生成相应的 API 文档。这些文档不仅提供给开发人员查阅和理解 API，还可以用于自动生成 API 文档的工具和服务。

在 SpringBoot 项目中配置

在 SpringBoot 项目中使用 Swagger annotations 需要进行一些配置。
使用 Swagger 注解的步骤如下：

在项目的pom.xml文件中添加 Swagger 依赖：

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

2. 在 Spring Boot 的启动类上添加@EnableSwagger2注解开启 Swagger 功能。

3. 在 Controller 类或方法上添加 Swagger 注解，描述接口的路径、请求方式、参数等。

4. 启动项目，访问http://localhost:端口号/swagger-ui.html可以查看生成的接口文档。

以下是一个使用 Swagger 注解的例子：

@RestController
@RequestMapping("/api")
@Api(tags = "用户管理")
public class UserController {
    
    @GetMapping("/user/{id}")
    @ApiOperation(value = "根据用户ID获取用户信息", notes = "根据用户ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    public User getUserById(@PathVariable Long id) {
        //...
    }
    
    @PostMapping("/user")
    @ApiOperation(value = "创建用户", notes = "创建用户")
    public User createUser(@RequestBody User user) {
        //...
    }
}

在上述例子中，@Api注解用于描述接口分组和名称，@ApiOperation注解用于描述接口的操作和说明，@ApiImplicitParam注解用于描述接口的参数。通过添加这些注解，Swagger 可以自动生成并展示接口文档。

注意事项

在使用 Swagger annotations 时，需要注意以下几个方面：

注解的使用应该准确无误，包括路径、参数、响应等信息。不正确的注解可能导致生成的 API 文档不准确或无法正常使用。
如果 API 的参数或响应比较复杂，可以考虑使用 @ApiModel 和 @ApiModelProperty 注解来描述更详细的信息。
注意对请求字段的校验和数据类型的限制，以避免潜在的安全隐患或错误。
版本兼容性问题，不同版本的 Swagger annotations 可能具有一些差异。在升级或使用新版本时，需要注意相关的兼容性问题。

更好的解决方案

Swagger 管理接口有时很不方便，缺乏一定的安全性和团队间的分享协作，所以我更推荐使用 Apifox 的 IDEA 插件。你可以在 IDEA 中自动同步 Swagger 注解到 Apifox，一键生成接口文档，多端同步，非常方便测试和维护，这样就可以迅速分享 API 给其他小伙伴。

立即体验 Apifox

Apifox 是一个比 Postman 更强大的接口测试工具，Apifox = Postman + Swagger + Mock + JMeter，Apifox 支持调试 http（s）、WebSocket、Socket、gRPC、Dubbo 等协议的接口，并且集成了 IDEA 插件。

Apifox 的 IDEA 插件可以自动解析代码注释，并基于 Javadoc、KDoc 和 ScalaDoc 生成 API 文档。通过 IntelliJ IDEA 的 Apifox Helper 插件，开发人员可以在不切换工具的情况下将他们的文档与 Apifox 项目同步。

当在 IDEA 项目中有接口信息变动，只需右键点击「 Upload to Apifox」一键即可完成同步，无需奔走相告。团队成员可在 Apifox 中看到同步后的最新内容。

现在出发去 JetBrains 插件市场下载试试吧！或直接在 IDEA 内「plugin」入口直接搜索 Apifox Helper。

知识扩展：

Swagger Array 使用详解
Swagger basepath 用法及常见问题详解

参考链接

Swagger 官方文档：https://swagger.io/docs/
Springfox 官方文档：https://springfox.github.io/springfox/docs/current/