Fastify Swagger：自动化API文档生成与展示

在现代软件开发中，API文档的生成和维护是一个不可或缺的环节。Fastify Swagger 是一个专为 Fastify 框架设计的插件，它能够自动生成符合 Swagger（OpenAPI v2 或 v3）规范的文档，从而帮助开发者轻松创建和维护API文档。本文将详细介绍 Fastify Swagger 的功能、用法以及一些重要的注意事项。
在这里插入图片描述

Fastify Swagger 的功能

Fastify Swagger 是一个强大的工具，它提供了以下主要功能：

自动化文档生成：能够从你的路由模式自动产生Swagger/OpenAPI定义，或者基于已有的Swagger/OpenAPI定义文件工作。
支持动态和静态模式：动态模式下自动从路由中生成API定义，而静态模式则允许你提供自己的Swagger定义文件。
集成Swagger UI：通过Fastify Swagger UI插件，你可以将OpenAPI规范定义的API文档以交互式的方式呈现给开发者或终端用户，支持自定义样式、JavaScript和CSS。

Fastify的环境

package.json

{"name": "fastifyproject","version": "1.0.0","main": "index.js","scripts": {"test": "echo \"Error: no test specified\" && exit 1"},"keywords": [],"author": "","license": "ISC","dependencies": {"@fastify/static": "^5.0.0","@fastify/swagger": "^9.2.0","@fastify/swagger-ui": "^5.1.0","fastify": "^5.1.0","fastify-cors": "^6.1.0","fastify-print-routes": "^4.0.0"}
}

Fastify Swagger 的用法

安装

首先，确保你有一个Fastify项目。然后，通过npm安装 @fastify/swagger 插件：

npm install @fastify/swagger
npm install @fastify/swagger-ui

main.js主文件

// main.js
const fastify = require('fastify')({ logger: true });
const swaggerConfig = require('./config/swagger');async function start() {// Your routes and other plugins go here// Register Swagger configurationawait swaggerConfig(fastify);fastify.register(require('./api/routes'), { prefix: '/v1' })// Start the servertry {await fastify.listen({ port: 3000 });fastify.log.info(`server listening on ${fastify.server.address().port}`);} catch (err) {fastify.log.error(err);process.exit(1);}
}start().catch(console.error);

swagger.js文件

// config/swagger.js
const fastifySwagger = require('@fastify/swagger');
const fastifySwaggerUi = require('@fastify/swagger-ui');module.exports = async function (fastify) {// Register Swaggerawait fastify.register(fastifySwagger, {routePrefix: '/swagger',exposeRoute: true});// Register Swagger UIawait fastify.register(fastifySwaggerUi, {routePrefix: '/swagger-ui',uiConfig: {docExpansion: 'full',deepLinking: false}// ... other configurations});// Redirect from /docs to the actual Swagger UIfastify.get('/docs', (req, reply) => {reply.redirect('/swagger-ui');});
};