在Next.js中集成swagger文档
<h2 id="前言">前言</h2><p>最近一直在用 Next.js 开发我的新网站</p>
<p>这次写了一些 API</p>
<p>我就想着能不能像平时开发后端那样，使用 swagger 进行调试</p>
<p>所以进行了一番调研</p>
<p>严格来说 <strong>Next.js 本身并不直接支持 swagger</strong>，因为 swagger（更准确地说是 <strong>OpenAPI 规范</strong>）是后端 API 文档的工具，而 Next.js 是一个前端/全栈框架。</p>
<p>不过，如果用 Next.js 的 <strong>API Routes</strong>（即 <code>app/api/*</code> 目录下的接口），完全可以结合 swagger 来做 API 文档。常见做法有两种：</p>
<ul>
<li>使用工具自动生成 swagger</li>
<li>手动写 OpenAPI 文件</li>
</ul>
<h2 id="自动生成">自动生成</h2>
<p>可以用工具根据 TypeScript 类型自动生成：</p>
<ul>
<li>tsoa</li>
<li>zod-to-openapi（如果用了 Zod 校验）</li>
<li>next-swagger-doc（专门为 Next.js 封装的工具）</li>
</ul>
<p>既然有为 Next.js 设计的工具，那我肯定直接用这第三个了</p>
<h2 id="next-swagger-doc">next-swagger-doc</h2>
<p>我实际用下来这个工具也不咋样</p>
<p>因为 Next.js 官方没有实现强类型的 API</p>
<p>所以需要自己定义每一个接口的 schema ，麻烦得一批</p>
<p>不过既然已经试用过了，也介绍一下吧</p>
<h3 id="安装">安装</h3>
<pre><code class="language-bash">bun i next-swagger-doc
</code></pre>
<h3 id="使用">使用</h3>
<p>这个工具的 README.md 文档有点老了</p>
<p>好在 examples 不老，里面有提供 Next.js 15 的项目例子</p>
<p>https://github.com/jellydn/next-swagger-doc/tree/main/examples</p>
<p>直接跟着配置吧</p>
<h3 id="创建-swagger-spec">创建 Swagger Spec</h3>
<p>创建 <code>lib/swagger.ts</code> 文件</p>
<pre><code class="language-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;
};
</code></pre>
<h3 id="创建-swagger-ui-component">创建 Swagger UI Component</h3>
<p>这个可以生成 swagger 的界面</p>
<p>有多种工具能实现这个功能</p>
<p>next-swagger-doc 用的是 swagger-ui-react</p>
<pre><code class="language-bash">bun i swagger-ui-react
</code></pre>
<p>我这里先跟着配置一下，等会再试试 Node.js 生态的其他工具，比如 stoplightio/elements</p>
<p>创建 <code>app/api-doc/react-swagger.tsx</code> 文件</p>
<pre><code class="language-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 typed
return <SwaggerUI spec={spec} />;
}
export default ReactSwagger;
</code></pre>
<h3 id="创建-api-文档页面">创建 API 文档页面</h3>
<p>就是把上面说的 Swagger UI Component 包装成页面</p>
<p>创建 <code>app/api-doc/page.tsx</code> 文件</p>
<pre><code class="language-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>
);
}
</code></pre>
<h3 id="添加接口文档注释">添加接口文档注释</h3>
<p>很麻烦，这个库不能根据路径自动识别接口，只能手动定义</p>
<p>添加后 swagger 文档的可读性更高</p>
<pre><code class="language-ts">/**
* @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>
<p>访问 http://localhost:3000/api-doc 查看接口文档</p>
<h2 id="手动生成">手动生成</h2>
<p>使用 swagger-jsdoc 之类的工具从 API route 上生成 OpenAPI spec</p>
<p>把 <code>swagger.json</code> 放在 <code>public</code> 目录里</p>
<p>然后搭配前面提到的 swagger-ui-react 之类的工具来实现 swagger 文档展示</p>
<pre><code class="language-tsx">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>
<p>可以参考: Swagger integration in next JS</p>
<h2 id="小结">小结</h2>
<p>这俩方法看起来都不是很完美</p>
<p>果然 Next.js 还是偏前端吧，写太多 API 也不合适</p>
<p>我最近又发现一个新玩意 hono ，这个框架对 edge 的支持非常好，可以考虑拿这个搭配 Next.js 来做一些小玩意</p>
<p>不得不说前端的技术栈更新太快了哈哈哈</p>
</div>
<div id="MySignature" role="contentinfo">
微信公众号：「程序设计实验室」
专注于互联网热门新技术探索与团队敏捷开发实践，包括架构设计、机器学习与数据分析算法、移动端开发、Linux、Web前后端开发等，欢迎一起探讨技术，分享学习实践经验。<br><br>
来源：https://www.cnblogs.com/deali/p/19069135/nextjs-integrate-swagger-docs
頁:
[1]