在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 类型自动生成:

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

next-swagger-doc

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

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

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

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

安装

bash 复制代码
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 文件

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

bash 复制代码
bun i swagger-ui-react

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

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

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;

创建 API 文档页面

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

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

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 文档的可读性更高

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,
  });
}

查看效果

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

手动生成

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

swagger.json 放在 public 目录里

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

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" />;
}

可以参考: Swagger integration in next JS

小结

这俩方法看起来都不是很完美

果然 Next.js 还是偏前端吧,写太多 API 也不合适

我最近又发现一个新玩意 hono ,这个框架对 edge 的支持非常好,可以考虑拿这个搭配 Next.js 来做一些小玩意

不得不说前端的技术栈更新太快了哈哈哈

相关推荐
wallflower202015 小时前
Next.js 全栈初体验 —— 用 Prisma + SQLite 搭建计数器
next.js
Mintopia2 天前
Next.js 新数据获取三剑客:fetch() + cache() + use —— 从引擎盖下聊到赛道上
前端·javascript·next.js
丁同亚的博客2 天前
echarts大屏项目指南
echarts·可视化·js·web前端·大屏
章丸丸3 天前
Tube - Studio Layout
react.js·next.js
小Lu的开源日常3 天前
Mathcheap v0.9.x 发布的第一个月,从想法到 MVP(最小可行性产品)
前端·图像识别·next.js
Mintopia4 天前
🌌 Next.js 服务端组件(Server Components)与客户端组件(`"use client"`)
前端·javascript·next.js
我想说一句5 天前
Next.js+Ollama本地聊天模型应用!
前端·next.js·ollama
Mintopia5 天前
App Router 与 `/app` 目录结构 & 布局系统的奇妙冒险 🏰
前端·javascript·next.js
FogLetter6 天前
Prisma + Next.js 全栈开发初体验:像操作对象一样玩转数据库
前端·后端·next.js