fastify结合fastify-swagger添加Doc类自定义非REST动词的方案咨询

实现方案（适配fastify@3.20.1 + fastify-swagger@4.8.4版本） #

你需要的自定义「Doc」项不需要硬改HTTP动词规则，也无需从零定制swagger-ui，两种实现路径如下：

方案1：路由伪装+标签分组（最优解，无需修改UI源码） #

完全复用fastify-swagger内置能力，零额外开发成本即可实现你要的展示效果：

• 注册fastify-swagger时开启openapi模式，配置tags定义你需要的「MySection」这类接口分区
• 新增一个伪装的GET路由，绑定对应分区标签，设置summary为Doc，路由逻辑可以直接返回你要的文档内容，也可以在schema的description字段写自定义说明
• 原有正常接口的标签和自定义Doc路由保持一致即可归到同一分区下

示例代码：

// 注册fastify-swagger
fastify.register(require('fastify-swagger'), {
  openapi: {
    info: { title: '接口文档', version: '1.0.0' },
    tags: [{ name: 'MySection', description: '自定义接口分区' }]
  },
  exposeRoute: true,
  routePrefix: '/docs'
})

// Doc自定义项对应的伪装路由
fastify.get('/my-section/doc', {
  schema: {
    tags: ['MySection'],
    summary: 'Doc',
    description: '这里可以写你要展示的自定义文档内容，支持markdown格式'
  }
}, async (req, reply) => {
  // 可直接返回文档内容
  return { doc: '自定义文档详情' }
})

// 原有正常业务路由
fastify.get('/my-section/data', { schema: { tags: ['MySection'], summary: 'GET' } }, () => {})
fastify.post('/my-section/data', { schema: { tags: ['MySection'], summary: 'POST' } }, () => {})

配置完成后swagger面板的MySection分组下，会按Doc→GET→POST的顺序展示，完全匹配你的需求。

方案2：自定义swagger UI接入fastify步骤 #

如果方案1无法满足你的特殊需求，确实需要修改swagger-ui源码，按以下步骤操作即可：

1. 拉取和fastify-swagger@4.8.4内置版本对齐的swagger-ui v4.x源码，完成自定义动词的渲染逻辑后编译出静态资源包
2. 将编译后的所有swagger-ui静态资源放到项目的public/custom-swagger目录下
3. 注册fastify-static插件托管该静态资源目录，关闭fastify-swagger的内置UI渲染，仅保留openapi.json生成能力，让自定义UI请求该json渲染即可

示例代码：

// 注册静态资源托管
fastify.register(require('fastify-static'), {
  root: `${__dirname}/public/custom-swagger`,
  prefix: '/custom-docs/'
})

// 注册fastify-swagger仅生成openapi定义
fastify.register(require('fastify-swagger'), {
  openapi: { info: { title: '接口文档', version: '1.0.0' } },
  exposeRoute: true,
  routePrefix: '/openapi.json',
  // 关闭内置UI
  uiConfig: false,
  uiHooks: false
})

修改自定义swagger-ui的index.html中openapi资源请求地址为/openapi.json，访问/custom-docs即可进入自定义后的文档页面。

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