当前位置：首页 > article >正文

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

article 2024/12/24 11:43:19

在现代软件开发中，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 configuration
    await swaggerConfig(fastify);
    fastify.register(require('./api/routes'), { prefix: '/v1' })
    // Start the server
    try {
        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 Swagger
    await fastify.register(fastifySwagger, {
        routePrefix: '/swagger',
        exposeRoute: true
    });

    // Register Swagger UI
    await fastify.register(fastifySwaggerUi, {
        routePrefix: '/swagger-ui',
        uiConfig: {
            docExpansion: 'full',
            deepLinking: false
        }
        // ... other configurations
    });

    // Redirect from /docs to the actual Swagger UI
    fastify.get('/docs', (req, reply) => {
        reply.redirect('/swagger-ui');
    });
};