如何配置Fastify+Swagger实现多版本API文档分路由展示

核心思路 #

每个API版本（v1/v2）需要通过独立的Fastify子上下文隔离，分别配置专属的Swagger和Swagger UI插件，确保各版本的路由Schema被精准收集到对应文档中，避免全局配置导致的Schema丢失或混编问题。

具体配置步骤 #

1. 调整项目结构（适配版本隔离） #

推荐的项目结构如下：

src/
├── plugins/
├── routes/
│   ├── v1/
│   │   ├── index.ts       # v1路由注册入口
│   │   └── test.ts        # v1测试接口
│   └── v2/
│       ├── index.ts       # v2路由注册入口
│       └── test.ts        # v2测试接口
├── swagger/
│   ├── v1-swagger.ts      # v1 Swagger配置插件
│   └── v2-swagger.ts      # v2 Swagger配置插件
└── server.ts               # 主服务入口

2. 编写版本专属Swagger插件 #

每个版本的Swagger需封装为独立插件，指定唯一的OpenAPI配置和文档路由前缀。

v1-swagger.ts

import fp from 'fastify-plugin';
import swagger from '@fastify/swagger';
import swaggerUi from '@fastify/swagger-ui';

export default fp(async (fastify) => {
  // 配置Swagger核心，用于收集v1路由Schema
  await fastify.register(swagger, {
    openapi: {
      openapi: '3.0.0',
      info: {
        title: 'API V1 Documentation',
        version: '1.0.0',
        description: 'V1版本API接口文档'
      },
      servers: [
        {
          url: 'http://127.0.0.1:4000/v1',
          description: '开发环境'
        }
      ]
    }
  });

  // 配置Swagger UI访问路由
  await fastify.register(swaggerUi, {
    routePrefix: '/v1/documentation',
    uiConfig: {
      docExpansion: 'full',
      deepLinking: false
    }
  });
});

v2-swagger.ts

import fp from 'fastify-plugin';
import swagger from '@fastify/swagger';
import swaggerUi from '@fastify/swagger-ui';

export default fp(async (fastify) => {
  await fastify.register(swagger, {
    openapi: {
      openapi: '3.0.0',
      info: {
        title: 'API V2 Documentation',
        version: '2.0.0',
        description: 'V2版本API接口文档'
      },
      servers: [
        {
          url: 'http://127.0.0.1:4000/v2',
          description: '开发环境'
        }
      ]
    }
  });

  await fastify.register(swaggerUi, {
    routePrefix: '/v2/documentation',
    uiConfig: {
      docExpansion: 'full',
      deepLinking: false
    }
  });
});

3. 主服务中注册版本上下文与路由 #

在server.ts中，为每个版本创建独立的Fastify子上下文，先注册对应版本的Swagger插件，再加载该版本的路由，确保Schema能被正确收集。

import Fastify from 'fastify';
import autoload from '@fastify/autoload';
import { join } from 'path';

const fastify = Fastify({
  logger: true
});

// 注册V1版本API与文档
await fastify.register(async (v1Fastify) => {
  await v1Fastify.register(import('./swagger/v1-swagger'));
  await v1Fastify.register(autoload, {
    dir: join(__dirname, 'routes', 'v1'),
    options: { prefix: '/v1' }
  });
});

// 注册V2版本API与文档
await fastify.register(async (v2Fastify) => {
  await v2Fastify.register(import('./swagger/v2-swagger'));
  await v2Fastify.register(autoload, {
    dir: join(__dirname, 'routes', 'v2'),
    options: { prefix: '/v2' }
  });
});

// 启动服务
await fastify.listen({ port: 4000 });

4. 规范定义路由Schema #

在各版本路由文件中，按照Fastify要求编写Schema，示例routes/v1/test.ts：

export default async (fastify) => {
  fastify.get('/test', {
    schema: {
      tags: ['测试接口'],
      summary: 'V1测试GET接口',
      response: {
        200: {
          type: 'object',
          properties: {
            message: { type: 'string' },
            version: { type: 'string' }
          }
        }
      }
    }
  }, async (request, reply) => {
    return { message: 'Hello from V1', version: 'v1' };
  });
};

5. 关键注意事项 #

• 必须为每个版本独立注册Swagger插件，全局复用会导致Schema收集失效或混编。
• 路由注册必须在对应版本的Swagger插件之后，确保Swagger能捕获路由的Schema信息。
• 使用fastify-plugin封装Swagger配置，保证插件配置能被子上下文正确继承。
• 你的依赖版本（@fastify/swagger@8.4.0、fastify@4.17.0等）兼容性正常，无需调整。

验证效果 #

启动服务后，访问以下地址即可看到对应版本的完整文档：

• V1文档：http://127.0.0.1:4000/v1/documentation
• V2文档：http://127.0.0.1:4000/v2/documentation

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