Swagger UI接口展示顺序定制方案：提升API文档可读性

2024-12-15 12:54:06

Swagger UI 接口展示顺序定制方案

在构建RESTful API时，Swagger UI作为强大的文档工具被广泛应用。但Swagger UI默认的接口展示排序方式可能无法满足个性化需求。当接口具有特定业务流程或依赖关系时，按字母或请求方法排序就显得不够直观。本文将深入探讨如何手动控制Swagger UI中接口的显示顺序。

问题分析

Swagger UI的接口展示顺序主要受Docket配置的影响。Docket是Swagger的核心组件，用于定义哪些接口需要生成文档以及如何展示。默认情况下，Docket并不提供直接根据业务逻辑定制接口顺序的功能。通常，接口会按照字母顺序或者请求方法（GET、POST等）进行排序，这与实际业务流程可能存在差异。如问题中所示，期望按照/start, /upload, /finalize, /checkStatus 的顺序展示接口，但默认排序却无法满足这一需求。

解决方案

要实现接口的手动排序，主要有以下几种方法：

1. 利用`@Api`的`position`属性

Swagger的@Api注解提供了position属性，可以用来控制Controller类在Swagger UI中的展示顺序。通过为不同的Controller设置不同的position值，即可调整它们在Swagger UI中的相对位置。数字越小，排序越靠前。

代码示例：

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/")
@Api(tags = "流程控制", position = 1) // 设置position值为1，最先展示
public class StartController {

    @PostMapping("/start")
    public String start(){
        return "started";
    }
}

@RestController
@RequestMapping("/")
@Api(tags = "文件处理", position = 2) // 设置position值为2，第二个展示
public class UploadController {
    @PostMapping("/upload")
    public String upload(){
        return "uploaded";
    }
}

@RestController
@RequestMapping("/")
@Api(tags = "流程控制", position = 3)// 设置position值为3，第三个展示
public class FinalizeController {

    @PostMapping("/finalize")
    public String finalizeProcess(){
        return "finalized";
    }
}

@RestController
@RequestMapping("/")
@Api(tags = "流程控制", position = 4)// 设置position值为4，最后展示
public class StatusController {

    @PostMapping("/checkStatus")
    public String checkStatus(){
        return "status checked";
    }
}

操作步骤:

确保项目中引入了Swagger相关的依赖。
在需要排序的Controller类上添加@Api注解，并设置position属性值。
重新启动应用，Swagger UI会根据position值对接口进行排序。

此方法通过设置不同Controller的position值实现接口分组和组内排序，简洁有效。需要注意的是，position的值为整数，不同@Api注解的position值决定其相对位置。

2. 使用`Tags`和`operationId`进行分组排序

另一种灵活的方法是利用@Api的tags属性以及@ApiOperation的nickname/operationId 属性(在Swagger 3.0.0+ 版本后推荐使用operationId) 。通过为接口分组，然后对组内的接口使用 nickname 或 operationId进行排序。nickname或operationId会影响同组内接口的排序。operationId是唯一的字符串标识符，Swagger UI会按字母顺序对它们进行排序。

代码示例：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/")
@Api(tags = "流程控制") // 所有接口属于 "流程控制" 分组
public class WorkflowController {

    @PostMapping("/start")
    @ApiOperation(value = "启动流程", tags="流程控制", nickname = "a_start", operationId ="a_start")// operationId 或 nickname 值以 'a' 开头
    public String start() {
        return "started";
    }

    @PostMapping("/upload")
    @ApiOperation(value = "上传文件", tags = "流程控制",nickname = "b_upload",operationId = "b_upload") // operationId 或 nickname 值以 'b' 开头
    public String upload() {
        return "uploaded";
    }

    @PostMapping("/finalize")
    @ApiOperation(value = "结束流程", tags = "流程控制",nickname = "c_finalize",operationId = "c_finalize") //  operationId 或 nickname 值以 'c' 开头
    public String finalizeProcess() {
        return "finalized";
    }

    @PostMapping("/checkStatus")
    @ApiOperation(value = "检查状态", tags = "流程控制" , nickname = "d_checkStatus",operationId ="d_checkStatus")// operationId 或 nickname 值以 'd' 开头
    public String checkStatus() {
        return "status checked";
    }
}

操作步骤:

在需要排序的Controller类上使用@Api注解，并设置相同的tags属性值，将相关接口归为一组。
在Controller类中的每个接口方法上使用@ApiOperation注解，并根据期望顺序设置 nickname或 operationId 属性值（按字母顺序设置）。Swagger 3.0.0+版本后更推荐使用operationId。
重新启动应用，Swagger UI会先按tags分组，然后按operationId/nickname字母顺序在组内排序接口。