@fastify/swagger访问/documentation返回404问题求助

问题描述 #

在基础Fastify项目中配置@fastify/swagger后，访问127.0.0.1:3000/documentation始终返回404错误，错误信息为：

"Route GET:/documentation not found"、{"statusCode":404}

相关代码及依赖如下：

server.js #

const fastify = require('fastify')({logger: true})
const PORT = 3000

fastify.register(require('./routes/items'));

fastify.register(require('@fastify/swagger'), {
    routePrefix: '/documentation',
    exposeRoute: true,
    swagger: {
        info: {
            title: { title: 'test'}
        }
    }
})

const start = async() => {
    try {
        await fastify.listen(PORT)
        fastify.swagger()
    } catch (error) {
        fastify.log.error(error)
        process.exit(1)
    }
}

start()

package.json 依赖 #

"dependencies": {
    "@fastify/swagger": "^8.1.0",
    "@fastify/view": "^7.1.2",
    "fastify": "^4.9.2",
    "uuid": "^9.0.0"
  }

问题原因 #

1. Swagger配置格式错误：swagger.info.title被错误设置为嵌套对象{ title: 'test' }，正确格式应为字符串值，格式错误会导致Swagger插件初始化异常。
2. 缺少可视化UI插件：@fastify/swagger仅负责生成OpenAPI规范的JSON数据，不提供可视化文档页面，需额外安装@fastify/swagger-ui支持/documentation的UI访问。

修复步骤 #

1. 修正Swagger配置格式 #

将swagger.info.title改为字符串，同时建议补充版本号符合OpenAPI规范：

fastify.register(require('@fastify/swagger'), {
    routePrefix: '/documentation',
    exposeRoute: true,
    swagger: {
        info: {
            title: 'test', // 改为字符串格式
            version: '1.0.0'
        }
    }
})

2. 安装并注册@fastify/swagger-ui #

先安装依赖：

npm install @fastify/swagger-ui

在server.js中于@fastify/swagger之后注册该插件：

// 先注册swagger核心插件
fastify.register(require('@fastify/swagger'), {
    routePrefix: '/documentation',
    exposeRoute: true,
    swagger: {
        info: {
            title: 'test',
            version: '1.0.0'
        }
    }
})

// 再注册swagger-ui可视化插件
fastify.register(require('@fastify/swagger-ui'), {
    routePrefix: '/documentation',
    uiConfig: {
        docExpansion: 'full', // 可选：默认展开所有文档节点
        deepLinking: true
    }
})

3. 移除不必要的手动调用 #

fastify.swagger()用于手动生成OpenAPI JSON，在已配置exposeRoute: true的情况下无需调用，可删除该语句：

const start = async() => {
    try {
        await fastify.listen({ port: PORT, host: '0.0.0.0' }) // 指定host方便外部访问
    } catch (error) {
        fastify.log.error(error)
        process.exit(1)
    }
}

验证 #

启动服务后，访问http://127.0.0.1:3000/documentation即可看到可视化Swagger文档页面，访问http://127.0.0.1:3000/documentation/json可查看生成的OpenAPI JSON数据。

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