在Next.js中集成swagger文档

岁岁安安 發表於 2025-9-18 15:36:00

<h1 class="postTitle">在Next.js中集成swagger文档</h1>
<div class="clear"> </div>
<div class="postBody">
<div id="cnblogs_post_body" class="blogpost-body cnblogs-markdown">
<h2 id="前言">前言#</h2>
最近一直在用 Next.js 开发我的新网站
这次写了一些 API
我就想着能不能像平时开发后端那样，使用 swagger 进行调试
所以进行了一番调研
严格来说 Next.js 本身并不直接支持 swagger，因为 swagger（更准确地说是 OpenAPI 规范）是后端 API 文档的工具，而 Next.js 是一个前端/全栈框架。
不过，如果用 Next.js 的 API Routes（即 <code>app/api/*</code> 目录下的接口），完全可以结合 swagger 来做 API 文档。常见做法有两种：
<ul>
<li>使用工具自动生成 swagger</li>
<li>手动写 OpenAPI 文件</li>
</ul>
<h2 id="自动生成">自动生成#</h2>
可以用工具根据 TypeScript 类型自动生成：
<ul>
<li>tsoa</li>
<li>zod-to-openapi（如果用了 Zod 校验）</li>
<li>next-swagger-doc（专门为 Next.js 封装的工具）</li>
</ul>
既然有为 Next.js 设计的工具，那我肯定直接用这第三个了
<h2 id="next-swagger-doc">next-swagger-doc#</h2>
我实际用下来这个工具也不咋样
因为 Next.js 官方没有实现强类型的 API
所以需要自己定义每一个接口的 schema ，麻烦得一批
不过既然已经试用过了，也介绍一下吧
<h3 id="安装">安装#</h3>
<pre class="highlighter-hljs"><code class="language-bash highlighter-hljs hljs">bun i next-swagger-doc
</code></pre>
<h3 id="使用">使用#</h3>
这个工具的 README.md 文档有点老了
好在 examples 不老，里面有提供 Next.js 15 的项目例子
https://github.com/jellydn/next-swagger-doc/tree/main/examples
直接跟着配置吧
<h3 id="创建-swagger-spec">创建 Swagger Spec#</h3>
创建 <code>lib/swagger.ts</code> 文件
<pre class="highlighter-hljs"><code class="language-ts highlighter-hljs hljs language-typescript">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;
};
</code></pre>
<h3 id="创建-swagger-ui-component">创建 Swagger UI Component#</h3>
这个可以生成 swagger 的界面
有多种工具能实现这个功能
next-swagger-doc 用的是 swagger-ui-react
<pre class="highlighter-hljs"><code class="language-bash highlighter-hljs hljs">bun i swagger-ui-react
</code></pre>
我这里先跟着配置一下，等会再试试 Node.js 生态的其他工具，比如 stoplightio/elements
创建 <code>app/api-doc/react-swagger.tsx</code> 文件
<pre class="highlighter-hljs"><code class="language-tsx highlighter-hljs hljs language-typescript">'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 typed
return <SwaggerUI spec={spec} />;
}

export default ReactSwagger;
</code></pre>
<h3 id="创建-api-文档页面">创建 API 文档页面#</h3>
就是把上面说的 Swagger UI Component 包装成页面
创建 <code>app/api-doc/page.tsx</code> 文件
<pre class="highlighter-hljs"><code class="language-tsx highlighter-hljs hljs language-typescript">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>
);
}
</code></pre>
<h3 id="添加接口文档注释">添加接口文档注释#</h3>
很麻烦，这个库不能根据路径自动识别接口，只能手动定义
添加后 swagger 文档的可读性更高
<pre class="highlighter-hljs"><code class="language-ts highlighter-hljs hljs language-typescript">/**
* @swagger
* /api/hello:
* get:
* description: Returns the hello world
* responses:
* 200:
* description: Hello World!
*/
export async function GET(_request: Request) {
// Do whatever you want
return new Response('Hello World!', {
status: 200,
});
}
</code></pre>
<h3 id="查看效果">查看效果#</h3>
访问 http://localhost:3000/api-doc 查看接口文档
<h2 id="手动生成">手动生成#</h2>
使用 swagger-jsdoc 之类的工具从 API route 上生成 OpenAPI spec
把 <code>swagger.json</code> 放在 <code>public</code> 目录里
然后搭配前面提到的 swagger-ui-react 之类的工具来实现 swagger 文档展示
<pre class="highlighter-hljs"><code class="language-tsx highlighter-hljs hljs language-typescript">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" />;
}
</code></pre>
可以参考: Swagger integration in next JS
<h2 id="小结">小结#</h2>
这俩方法看起来都不是很完美
果然 Next.js 还是偏前端吧，写太多 API 也不合适
我最近又发现一个新玩意 hono ，这个框架对 edge 的支持非常好，可以考虑拿这个搭配 Next.js 来做一些小玩意
不得不说前端的技术栈更新太快了哈哈哈
</div>
<div class="esa-post-signature">
作者：DealiAxy
出处：https://www.cnblogs.com/deali/p/19069135/nextjs-integrate-swagger-docs
版权：本作品采用「署名-非商业性使用-相同方式共享 4.0 国际」许可协议进行许可。
微信公众号：「程序设计实验室」 新版StarBlog已经上线，地址：http://blog.deali.cn

</div>
<div id="MySignature">微信公众号：「程序设计实验室」专注于互联网热门新技术探索与团队敏捷开发实践，包括架构设计、机器学习与数据分析算法、移动端开发、Linux、Web前后端开发等，欢迎一起探讨技术，分享学习实践经验。</div>

</div>

</div>
<div id="MySignature" role="contentinfo">
漫思 
来源：https://www.cnblogs.com/sexintercourse/p/19098910

頁: [1]

琼殿技术论坛's Archiver

在Next.js中集成swagger文档