Express中限制Swagger文档可见性：指定API/标签文档配置

嘿，这两个需求都能轻松实现！我结合Express常用的Swagger工具（swagger-jsdoc + swagger-ui-express）给你一步步拆解操作方法～

有两种常用方案，按需选择：

方式1：固定展示指定标签的API（后端提前过滤） #

先生成完整的Swagger规范，再手动筛选出包含目标标签的API，最后传给Swagger UI渲染：

const express = require('express');
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const app = express();

// 1. 生成完整的Swagger规范
const fullSwaggerSpec = swaggerJsdoc({
  definition: {
    openapi: '3.0.0',
    info: {
      title: '我的API文档',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'], // 替换成你的路由文件路径
});

// 2. 过滤出仅包含"user"标签的API
const userFilteredSpec = {
  ...fullSwaggerSpec,
  paths: Object.fromEntries(
    Object.entries(fullSwaggerSpec.paths).filter(([path, methods]) => {
      // 检查该路径下的任意请求方法是否带有目标标签
      return Object.values(methods).some(method => 
        method.tags && method.tags.includes('user')
      );
    })
  )
};

// 3. 挂载过滤后的Swagger UI
app.use('/docs/users', swaggerUi.serve, swaggerUi.setup(userFilteredSpec));

访问localhost:port/docs/users就只会看到带user标签的API了。

方式2：允许用户在UI上自行过滤标签（前端可控） #

如果不想固定死展示范围，想让用户自由切换查看不同标签的API，可以开启Swagger UI的探索模式：

app.use('/docs', swaggerUi.serve, swaggerUi.setup(fullSwaggerSpec, {
  explorer: true, // 开启后页面会出现标签选择器
  queryConfigEnabled: true // 支持通过URL参数直接过滤，比如 /docs?tags=user
}));

开启后，用户可以在Swagger UI页面的搜索框输入标签名称过滤，也能直接通过URL参数指定要查看的标签。

其实可以基于上面的过滤逻辑，为每个标签单独生成一个Swagger UI实例，挂载到不同的路由上：

// 定义要单独展示的标签与对应路由
const tagRouteMap = [
  { tag: 'user', route: '/docs/users' },
  { tag: 'product', route: '/docs/products' },
  { tag: 'order', route: '/docs/orders' },
];

// 批量生成各标签的独立文档路由
tagRouteMap.forEach(({ tag, route }) => {
  const filteredSpec = {
    ...fullSwaggerSpec,
    paths: Object.fromEntries(
      Object.entries(fullSwaggerSpec.paths).filter(([path, methods]) => {
        return Object.values(methods).some(method => 
          method.tags && method.tags.includes(tag)
        );
      })
    )
  };
  // 还可以给每个文档页设置自定义标题
  app.use(route, swaggerUi.serve, swaggerUi.setup(filteredSpec, {
    customSiteTitle: `${tag.charAt(0).toUpperCase() + tag.slice(1)} 专属API文档`
  }));
});

// 可选：保留完整文档的访问路由
app.use('/docs', swaggerUi.serve, swaggerUi.setup(fullSwaggerSpec));

这样访问/docs/users看用户相关API，/docs/products看商品相关API，每个标签的文档完全独立。

要让过滤逻辑生效，你的路由文件里必须给API正确添加Swagger标签注释，比如：

/**
 * @swagger
 * /api/users:
 *   get:
 *     tags:
 *       - user
 *     summary: 获取用户列表
 *     responses:
 *       200:
 *         description: 成功返回用户列表数据
 */
app.get('/api/users', (req, res) => {
  res.json([{ id: 1, name: '张三' }]);
});

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