Node.js项目中如何按标签与HTTP动词排序swagger.json接口顺序

实现原理 #

Swagger UI 原生提供了排序配置项，无需修改业务代码或Swagger注解、无需新增冗余标签，仅需调整UI初始化参数即可实现需求。

不同集成场景的配置方法 #

场景1：使用 swagger-ui-express（Express 生态通用方案） #

这是Express项目最常用的Swagger集成方案，直接在swagger-ui初始化时增加operationsSorter配置即可：

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json'); // 替换为你的swagger文件路径

// 自定义HTTP动词优先级，排在数组前面的优先展示，可按需调整顺序
const HTTP_METHOD_PRIORITY = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head'];

const swaggerUiOptions = {
  // 标签排序：按标签名称字母升序，也可自定义排序规则
  tagsSorter: 'alpha',
  // 接口排序核心规则
  operationsSorter: (a, b) => {
    // 第一步：优先按标签分组排序，相同标签的接口排在一起
    const aTag = a.get('tags')[0];
    const bTag = b.get('tags')[0];
    const tagSortResult = aTag.localeCompare(bTag);
    if (tagSortResult !== 0) return tagSortResult;

    // 第二步：同标签下按自定义的HTTP动词顺序排序
    const aMethod = a.get('method');
    const bMethod = b.get('method');
    return HTTP_METHOD_PRIORITY.indexOf(aMethod) - HTTP_METHOD_PRIORITY.indexOf(bMethod);
  }
};

// 挂载swagger接口文档路由
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, swaggerUiOptions));

按上述配置后，你的示例中Animals标签下的3个接口就会按照get /api/animals/elephant、get /api/animals/dog、post /api/animals/elephant的顺序展示，完全匹配你的预期。

场景2：使用 @fastify/swagger-ui（Fastify 生态方案） #

Fastify生态的配置逻辑完全一致，仅配置挂载方式略有差异：

await fastify.register(require('@fastify/swagger-ui'), {
  routePrefix: '/api-docs',
  uiConfig: {
    tagsSorter: 'alpha',
    operationsSorter: (a, b) => {
      const HTTP_METHOD_PRIORITY = ['get', 'post', 'put', 'patch', 'delete'];
      return HTTP_METHOD_PRIORITY.indexOf(a.method) - HTTP_METHOD_PRIORITY.indexOf(b.method);
    }
  }
})

其他说明 #

如果你是通过swagger-jsdoc动态生成swagger.json的场景，调整规则完全相同，仅需按上述方法修改UI配置即可，无需改动接口注解逻辑。

内容的提问来源于stack exchange，提问作者Mimi