在Next.js中集成swagger文档

前言

最近一直在用 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 ，麻烦得一批
不过既然已经试用过了，也介绍一下吧
安装

1. 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 文件

1. import { createSwaggerSpec } from 'next-swagger-doc';
3. import 'server-only';
5. export const getApiDocs = async () => {
6.   const spec = createSwaggerSpec({
7.     apiFolder: 'app/api',
8.     definition: {
9.       openapi: '3.0.0',
10.       info: {
11.         title: 'Next Swagger API Example',
12.         version: '1.0',
13.       },
14.       components: {
15.         securitySchemes: {
16.           BearerAuth: {
17.             type: 'http',
18.             scheme: 'bearer',
19.             bearerFormat: 'JWT',
20.           },
21.           OAuth2: {
22.             type: 'oauth2',
23.             flows: {
24.               authorizationCode: {
25.                 authorizationUrl: 'https://example.com/oauth/authorize',
26.                 tokenUrl: 'https://example.com/oauth/token',
27.                 scopes: {
28.                   read: 'Grants read access',
29.                   write: 'Grants write access',
30.                 },
31.               },
32.             },
33.           },
34.         },
35.       },
36.       security: [],
37.     },
38.   });
39.   return spec;
40. };

复制代码

创建 Swagger UI Component

这个可以生成 swagger 的界面
有多种工具能实现这个功能
next-swagger-doc 用的是 swagger-ui-react

1. bun i swagger-ui-react

复制代码

我这里先跟着配置一下，等会再试试 Node.js 生态的其他工具，比如 stoplightio/elements
创建 app/api-doc/react-swagger.tsx 文件

1. 'use client';
3. import SwaggerUI from 'swagger-ui-react';
5. import 'swagger-ui-react/swagger-ui.css';
7. type Props = {
8.     spec: Record<string, any>;
9. };
11. function ReactSwagger({ spec }: Props) {
12.     // @ts-ignore - SwaggerUI is not typed
13.     return <SwaggerUI spec={spec} />;
14. }
16. export default ReactSwagger;

复制代码

创建 API 文档页面

就是把上面说的 Swagger UI Component 包装成页面
创建 app/api-doc/page.tsx 文件

1. import { getApiDocs } from '@/lib/swagger';
3. import ReactSwagger from './react-swagger';
5. export default async function IndexPage() {
6.   const spec = await getApiDocs();
7.   return (
8.     <section className="container">
9.       <ReactSwagger spec={spec} />
10.     </section>
11.   );
12. }

复制代码

添加接口文档注释

很麻烦，这个库不能根据路径自动识别接口，只能手动定义
添加后 swagger 文档的可读性更高

1. /**
2. * @swagger
3. * /api/hello:
4. *   get:
5. *     description: Returns the hello world
6. *     responses:
7. *       200:
8. *         description: Hello World!
9. */
10. export async function GET(_request: Request) {
11.   // Do whatever you want
12.   return new Response('Hello World!', {
13.     status: 200,
14.   });
15. }

复制代码

查看效果

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

使用 swagger-jsdoc 之类的工具从 API route 上生成 OpenAPI spec
把 swagger.json 放在 public 目录里
然后搭配前面提到的 swagger-ui-react 之类的工具来实现 swagger 文档展示

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

复制代码

可以参考: Swagger integration in next JS
小结

这俩方法看起来都不是很完美
果然 Next.js 还是偏前端吧，写太多 API 也不合适
我最近又发现一个新玩意 hono ，这个框架对 edge 的支持非常好，可以考虑拿这个搭配 Next.js 来做一些小玩意
不得不说前端的技术栈更新太快了哈哈哈

来源：豆瓜网用户自行投稿发布，如果侵权，请联系站长删除