解决 Fastify 框架中 Swagger API 文档的 404 报错-JavaScript中文网-JavaScript教程资源分享门户

解决 Fastify 框架中 Swagger API 文档的 404 报错

前言

在使用 Fastify 框架开发 API 的过程中，Swagger API 文档是一个非常有用的工具。通过 Swagger API 文档，我们可以很方便的了解 API 的接口文档和参数说明。然而，在使用 Fastify 内置的 fastify-swagger 插件生成 Swagger API 文档时，有时候会出现 404 报错情况。这篇文章将会介绍如何解决 Fastify 框架中 Swagger API 文档的 404 报错。

问题描述

当使用 Fastify 内置的 fastify-swagger 插件生成 Swagger API 文档时，可能会出现如下的 404 报错：

Cannot GET /swagger/static/swagger-ui.css
Cannot GET /swagger/static/swagger-ui-bundle.js
Cannot GET /swagger/static/swagger-ui-standalone-preset.js

此时，我们无法通过链接访问 Swagger API 文档，这会给 API 的使用者带来很大的不便。

解决方法

1. 修改 Swagger UI 的路径

Fastify 内置的 fastify-swagger 插件默认使用了 Swagger UI，Swagger UI 的路径默认在 /swagger/ 下。然而，有时候为了避免与其他路径冲突，我们需要将 Swagger UI 的路径修改为其他路径。

// javascriptcn.com 代码示例
fastify.register(require('fastify-swagger'), {
  exposeRoute: true,
  swagger: {
    info: {
      title: 'API',
      description: 'API documentation',
      version: '1.0.0'
    },
    host: 'localhost:3000',
    schemes: ['http'],
    consumes: ['application/json'],
    produces: ['application/json'],
    securityDefinitions: {
      basicAuth: {
        type: 'basic'
      }
    },
    securityHandlers: {
      basicAuth: function (req, res, done) {
         done()
      }
    },
    /* 修改 Swagger UI 的路径 */
    routePrefix: '/docs',
  },
  /* 修改 Swagger UI 的路径 */
  uiConfig: {
    swaggerOptions: {
      url: '/docs/json'
    }
  }
})

在 swagger 配置中添加 routePrefix 属性来修改 Swagger UI 的路径，同时在 uiConfig 配置中将 Swagger UI 的链接地址修改为新的路径 /docs/json。

2. 添加 Fastify 静态文件的中间件

Fastify 内置的 fastify-static 插件可以很方便的将静态文件服务出去。我们可以使用 fastify-static 插件，将 Swagger UI 的静态文件服务出去，以解决 404 报错的问题。

const path = require('path')
fastify.register(require('fastify-static'), {
  root: path.join(__dirname, 'public'),
  prefix: '/swagger/', // Swagger UI 的路径
})

在上述例子中，我们将服务静态文件的根目录设置为 public，并设置前缀为 /swagger/。这样，通过访问 <host>:<port>/swagger/static/swagger-ui.css 就可以访问到 Swagger UI 的静态文件了。

3. 简化 Swagger UI

Swagger UI 静态文件中包含了很多我们用不到的代码，直接服务出去会造成静态文件的浪费，影响网站的加载速度。我们可以通过使用 fastify-static 插件，将 Swagger UI 静态文件进行简化，只保留我们需要的部分。

// javascriptcn.com 代码示例
const path = require('path')
fastify.register(require('fastify-static'), {
  root: path.join(__dirname, 'public'),
  prefix: '/swagger/', // Swagger UI 的路径
  decorateReply: false,
  appendRequestPath: false,
  serve(request, reply) {
    const fileName = request.url.split('/').pop()
    if (fileName === 'swagger-ui.css'
        || fileName === 'swagger-ui-bundle.js'
        || fileName === 'swagger-ui-standalone-preset.js') {
      reply.sendFile(fileName)
    }
  }
})

在上述例子中，我们在 serve 方法中根据请求的 URL 判断是否需要服务出去对应的静态文件。只有请求的链接是 swagger-ui.css、swagger-ui-bundle.js 或 swagger-ui-standalone-preset.js 时，才会将对应的静态文件服务出去。

总结

本文介绍了解决 Fastify 框架中 Swagger API 文档的 404 报错的三种方法：修改 Swagger UI 的路径、添加 Fastify 静态文件的中间件和简化 Swagger UI。这些方法可以有效的解决 Swagger API 文档的 404 报错问题，并且可以提高 API 的可读性和可用性。希望这篇文章对你解决类似问题有所帮助。

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/651c56ee95b1f8cacd3de93f