Swagger 中接口如何排序？

Swagger 提供了接口排序的功能，我们可以通过配置注解来实现 API 的排序，使得 API 文档更加清晰、易读。

Swagger 接口排序使用场景

在实际的开发过程中，我们的项目可能会包含大量的 API 接口，而这些接口可能涉及到多个不同的业务模块。如果我们将这些接口按照一定的顺序进行排序，那么开发者和测试人员就可以更快地找到他们需要的接口，从而提高工作效率。此外，对 API 进行排序也可以使得 API 文档看起来更加整洁、有条理。

Swagger 接口排序用法

在 Swagger 中，我们可以通过 @ApiOperation 注解来实现 API 的排序。@ApiOperation 注解包含一个 position 属性，我们可以通过设置这个属性的值来改变 API 在文档中的位置。position 的值越小，API 在文档中的位置越靠前。

实践案例

我们可以这样配置 @ApiOperation 注解：

@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息", position = 1)
@GetMapping("/getUserInfo")
public User getUserInfo(@RequestParam String userId) {
    // 业务逻辑
}

在这个例子中，我们将 position 的值设置为 1，这意味着 "获取用户信息" 这个 API 将会在文档的最前面。

在 SpringBoot 项目中配置

在 SpringBoot 项目中，我们可以在 Controller 类的方法上添加 @ApiOperation 注解，并配置 position 属性。例如：

@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息", position = 1)
    @GetMapping("/getUserInfo")
    public User getUserInfo(@RequestParam String userId) {
        // 业务逻辑
    }

    @ApiOperation(value = "更新用户信息", notes = "根据用户ID更新用户信息", position = 2)
    @PutMapping("/updateUserInfo")
    public User updateUserInfo(@RequestBody User user) {
        // 业务逻辑
    }
}

在这个例子中，我们将 "获取用户信息" 这个 API 的 position 设置为 1，将 "更新用户信息" 这个 API 的 position 设置为 2。这样，"获取用户信息" 这个 API 就会在 "更新用户信息" 这个 API 之前显示在文档中。

注意事项

position 属性的值必须是整数，且值越小，API 在文档中的位置越靠前。
如果多个 API 的 position 值相同，那么它们在文档中的顺序是不确定的。因此，我们需要确保每个 API 的 position 值都是唯一的。
position 属性只能影响同一级别的 API 的排序，不能影响不同级别的 API 的排序。

常见问题与解决方案

Q: 如果我没有配置 position 属性，那么 API 在文档中的顺序是怎样的？

A: 如果没有配置 position 属性，那么 API 在文档中的顺序默认是按照代码中的顺序来的。

Q:即使设置了 @ApiOperation 注解的 position 属性，API 在文档中的顺序仍然不正确？

A：这可能是因为 Swagger2 在解析 API 时，是按照源代码中的顺序进行的。因此，如果要改变 API 在文档中的顺序，除了设置 position 属性外，还需要改变源代码中的顺序。

Swagger 和 Apifox 整合

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。

知识扩展：

参考链接：