Next-Swagger-Doc 使用教程

Next-Swagger-Doc 使用教程

next-swagger-docThis package reads your JSDoc-annotated source code on NextJS API route and generates an OpenAPI (Swagger) specification.项目地址:https://gitcode.com/gh_mirrors/ne/next-swagger-doc

1. 项目介绍

Next-Swagger-Doc 是一个用于生成 Swagger JSON API 的工具，适用于 Next.js 项目。它通过读取 Next.js API 路由中的 JSDoc 注释，自动生成 OpenAPI (Swagger) 规范文档。生成的文档可以用于展示 API 接口，方便开发者进行接口测试和文档查阅。

2. 项目快速启动

安装

首先，确保你已经安装了 Node.js 和 Yarn。然后，在你的 Next.js 项目中安装 next-swagger-doc：

yarn add next-swagger-doc

配置

1. 创建 Swagger 规范文件

   在你的项目中创建一个 lib/swagger.ts 文件，并添加以下内容：

   import { createSwaggerSpec } from "next-swagger-doc";
   
   export const getApiDocs = async () => {
     const spec = createSwaggerSpec({
       apiFolder: "app/api", // 定义 API 文件夹
       definition: {
         openapi: "3.0.0",
         info: {
           title: "Next Swagger API Example",
           version: "1.0",
         },
         components: {
           securitySchemes: {
             BearerAuth: {
               type: "http",
               scheme: "bearer",
               bearerFormat: "JWT",
             },
           },
         },
         security: [],
       },
     });
     return {
       props: {
         spec,
       },
     };
   };
   

2. 创建 API 路由

   在你的 Next.js 项目中创建一个 API 路由，例如 pages/api/doc.ts，并添加以下内容：

   import { withSwagger } from "next-swagger-doc";
   
   const swaggerHandler = withSwagger({
     definition: {
       openapi: "3.0.0",
       info: {
         title: "NextJS Swagger",
         version: "0.1.0",
       },
     },
     apiFolder: "pages/api",
   });
   
   export default swaggerHandler();
   

3. 添加 JSDoc 注释

   在你的 API 路由中添加 JSDoc 注释，例如 pages/api/hello.ts：

   import { NextApiRequest, NextApiResponse } from "next";
   
   /**
    * @swagger
    * /api/hello:
    *   get:
    *     description: Returns the hello world
    *     responses:
    *       200:
    *         description: hello world
    */
   const handler = (_req: NextApiRequest, res: NextApiResponse) => {
     res.status(200).json({ result: "hello world" });
   };
   
   export default handler;
   

4. 访问 Swagger 文档

   启动你的 Next.js 项目，然后在浏览器中访问 http://localhost:3000/api-doc 或 http://localhost:3000/，即可查看生成的 Swagger 文档。

3. 应用案例和最佳实践

应用案例

Next-Swagger-Doc 可以用于任何需要生成 API 文档的 Next.js 项目。例如，在一个电商平台的后端服务中，使用 Next-Swagger-Doc 可以自动生成商品管理、订单管理等 API 的文档，方便前端开发者和测试人员查阅和测试。

最佳实践

1. 保持 JSDoc 注释的完整性：确保每个 API 路由都有详细的 JSDoc 注释，以便生成完整的 Swagger 文档。
2. 定期更新文档：随着 API 的迭代，定期更新 JSDoc 注释，确保生成的 Swagger 文档与实际 API 一致。
3. 使用安全方案：在 Swagger 文档中定义安全方案（如 JWT 认证），确保 API 的安全性。

4. 典型生态项目

Next-Swagger-Doc 可以与以下项目结合使用，提升开发效率和文档质量：

1. Next.js：Next-Swagger-Doc 是专为 Next.js 设计的，可以无缝集成到 Next.js 项目中。
2. Swagger UI：Next-Swagger-Doc 生成的 Swagger 文档可以直接在 Swagger UI 中展示，方便开发者进行接口测试。
3. Zod：结合 Zod 进行 API 参数校验，确保 API 的输入数据符合预期。
4. Fastest-Validator：使用 Fastest-Validator 进行快速的数据校验，提升 API 的响应速度。

通过以上步骤，你可以快速上手并使用 Next-Swagger-Doc 生成高质量的 API 文档。

next-swagger-docThis package reads your JSDoc-annotated source code on NextJS API route and generates an OpenAPI (Swagger) specification.项目地址:https://gitcode.com/gh_mirrors/ne/next-swagger-doc