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

在Next.js中集成swagger文档

news 2025/11/4 11:30:48

前言

最近一直在用 Next.js 开发我的新网站

这次写了一些 API

我就想着能不能像平时开发后端那样，使用 swagger 进行调试

所以进行了一番调研

严格来说 Next.js 本身并不直接支持 swagger，因为 swagger（更准确地说是 OpenAPI 规范）是后端 API 文档的工具，而 Next.js 是一个前端/全栈框架。

不过，如果用 Next.js 的 API Routes（即 app/api/* 目录下的接口），完全可以结合 swagger 来做 API 文档。常见做法有两种：

使用工具自动生成 swagger
手动写 OpenAPI 文件

自动生成

可以用工具根据 TypeScript 类型自动生成：

tsoa
zod-to-openapi（如果用了 Zod 校验）
next-swagger-doc（专门为 Next.js 封装的工具）

既然有为 Next.js 设计的工具，那我肯定直接用这第三个了

next-swagger-doc

我实际用下来这个工具也不咋样

因为 Next.js 官方没有实现强类型的 API

所以需要自己定义每一个接口的 schema ，麻烦得一批

不过既然已经试用过了，也介绍一下吧

安装

bun i next-swagger-doc

使用

这个工具的 README.md 文档有点老了

好在 examples 不老，里面有提供 Next.js 15 的项目例子

https://github.com/jellydn/next-swagger-doc/tree/main/examples

直接跟着配置吧

创建 Swagger Spec

创建 lib/swagger.ts 文件

import { createSwaggerSpec } from 'next-swagger-doc';import 'server-only';export const getApiDocs = async () => {const spec = createSwaggerSpec({apiFolder: 'app/api',definition: {openapi: '3.0.0',info: {title: 'Next Swagger API Example',version: '1.0',},components: {securitySchemes: {BearerAuth: {type: 'http',scheme: 'bearer',bearerFormat: 'JWT',},OAuth2: {type: 'oauth2',flows: {authorizationCode: {authorizationUrl: 'https://example.com/oauth/authorize',tokenUrl: 'https://example.com/oauth/token',scopes: {read: 'Grants read access',write: 'Grants write access',},},},},},},security: [],},});return spec;
};

创建 Swagger UI Component

这个可以生成 swagger 的界面

有多种工具能实现这个功能

next-swagger-doc 用的是 swagger-ui-react

bun i swagger-ui-react

我这里先跟着配置一下，等会再试试 Node.js 生态的其他工具，比如 stoplightio/elements

创建 app/api-doc/react-swagger.tsx 文件

'use client';import SwaggerUI from 'swagger-ui-react';import 'swagger-ui-react/swagger-ui.css';type Props = {spec: Record<string, any>;
};function ReactSwagger({ spec }: Props) {// @ts-ignore - SwaggerUI is not typedreturn <SwaggerUI spec={spec} />;
}export default ReactSwagger;

创建 API 文档页面

就是把上面说的 Swagger UI Component 包装成页面

创建 app/api-doc/page.tsx 文件

import { getApiDocs } from '@/lib/swagger';import ReactSwagger from './react-swagger';export default async function IndexPage() {const spec = await getApiDocs();return (<section className="container"><ReactSwagger spec={spec} /></section>);
}

添加接口文档注释

很麻烦，这个库不能根据路径自动识别接口，只能手动定义

添加后 swagger 文档的可读性更高

/*** @swagger* /api/hello:*   get:*     description: Returns the hello world*     responses:*       200:*         description: Hello World!*/
export async function GET(_request: Request) {// Do whatever you wantreturn new Response('Hello World!', {status: 200,});
}

查看效果

访问 http://localhost:3000/api-doc 查看接口文档

手动生成

使用 swagger-jsdoc 之类的工具从 API route 上生成 OpenAPI spec

把 swagger.json 放在 public 目录里

然后搭配前面提到的 swagger-ui-react 之类的工具来实现 swagger 文档展示

import dynamic from 'next/dynamic';const SwaggerUI = dynamic(() => import('swagger-ui-react'), { ssr: false });
import 'swagger-ui-react/swagger-ui.css';export default function ApiDocs() {return <SwaggerUI url="/swagger.json" />;
}

可以参考: Swagger integration in next JS