Welcome to next-swagger-doc 👋

Generate Swagger JSON API from NextJS Api Routes

_{If you enjoy working with next-swagger-doc, you will love next-validations: NextJS API Validations, support Zod, Yup, Fastest-Validator, Joi, and more}

🏠 Homepage

✨ Demo

Prerequisites

• Nextjs >= 9
• Node >= 18

Motivation

This package reads your JSDoc-annotated source code on NextJS API route and generates an OpenAPI (Swagger) specification.

nextjs + swagger-jsdoc = next-swagger-doc

Install

1yarn add next-swagger-doc

Usage #1: next-swagger-doc with Next.js 13

To incorporate next-swagger-doc with your Next.js 13 project, follow these steps. This setup will generate Swagger documentation for your API based on your code and provide a built-in Swagger UI for viewing the documentation.

1. Create Swagger Spec

Next, create a new file lib/swagger.ts. This file uses the next-swagger-doc library to create a Swagger specification based on the API routes in your Next.js project.

1import { createSwaggerSpec } from "next-swagger-doc";
2
3export const getApiDocs = async () => {
4  const spec = createSwaggerSpec({
5    apiFolder: "app/api", // define api folder under app folder
6    definition: {
7      openapi: "3.0.0",
8      info: {
9        title: "Next Swagger API Example",
10        version: "1.0",
11      },
12      components: {
13        securitySchemes: {
14          BearerAuth: {
15            type: "http",
16            scheme: "bearer",
17            bearerFormat: "JWT",
18          },
19        },
20      },
21      security: [],
22    },
23  });
24  return spec;
25};

2. Create Swagger UI Component

Generate a new file named app/api-doc/react-swagger.tsx. In this file, create and export a React component that utilizes the swagger-ui-react library to render the Swagger UI according to the provided specification.

For demonstration purposes, here is an example using swagger-ui-react

Feel free to employ any alternative swagger UI library, such as stoplightio/elements. I have added an example using this library in the example folder.

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

3. Create API Documentation Page

Create a new file app/api-doc/page.tsx. This page imports the Swagger spec and the Swagger UI component to display the Swagger documentation.

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

4. Add Swagger Comment to API Route

Lastly, add a Swagger comment to your API route in app/api/hello/route.ts. This comment includes metadata about the API endpoint which will be read by next-swagger-doc and included in the Swagger spec.

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

Now, navigate to localhost:3000/api-doc (or wherever you host your Next.js application), and you should see the swagger UI.

Usage #2: Create an single API document

1yarn add next-swagger-doc swagger-ui-react

• Create an live swagger page, e.g: pages/api-doc.tsx

1import { GetStaticProps, InferGetStaticPropsType } from 'next';
2import { createSwaggerSpec } from 'next-swagger-doc';
3import dynamic from 'next/dynamic';
4import 'swagger-ui-react/swagger-ui.css';
5
6const SwaggerUI = dynamic<{
7  spec: any;
8}>(import('swagger-ui-react'), { ssr: false });
9
10function ApiDoc({ spec }: InferGetStaticPropsType<typeof getStaticProps>) {
11  return <SwaggerUI spec={spec} />;
12}
13
14export const getStaticProps: GetStaticProps = async () => {
15  const spec: Record<string, any> = createSwaggerSpec({
16    apiFolder: 'pages/api' // or 'src/pages/api',
17    definition: {
18      openapi: '3.0.0',
19      info: {
20        title: 'Next Swagger API Example',
21        version: '1.0',
22      },
23    },
24  });
25
26  return {
27    props: {
28      spec,
29    },
30  };
31};
32
33export default ApiDoc;

Usage #3: Use NextJS API route to create Swagger JSON spec

• Step 1: Create an api route on nextjs, e.g: pages/api/doc.ts

1import { withSwagger } from "next-swagger-doc";
2
3const swaggerHandler = withSwagger({
4  definition: {
5    openapi: "3.0.0",
6    info: {
7      title: "NextJS Swagger",
8      version: "0.1.0",
9    },
10  },
11  apiFolder: "pages/api",
12});
13export default swaggerHandler();

• Step 2: Add JSdoc to any NextJS API routes, for example: pages/api/hello.ts

1import { NextApiRequest, NextApiResponse } from "next";
2
3/**
4 * @swagger
5 * /api/hello:
6 *   get:
7 *     description: Returns the hello world
8 *     responses:
9 *       200:
10 *         description: hello world
11 */
12const handler = (_req: NextApiRequest, res: NextApiResponse) => {
13  res.status(200).json({
14    result: "hello world",
15  });
16};
17
18export default handler;

• Step 3: Access the Swagger API doc

Usage #4: Generate Swagger file from CLI

• Step 1: create a JSON config file as next-swagger-doc.json

1{
2  "apiFolder": "pages/api",
3  "schemaFolders": ["models"],
4  "definition": {
5    "openapi": "3.0.0",
6    "info": {
7      "title": "Next Swagger API Example",
8      "version": "1.0"
9    }
10  }
11}

• Step 2: run cli for generating swagger file

1yarn next-swagger-doc-cli next-swagger-doc.json

Run example app

1gh repo clone jellydn/next-swagger-doc
2cd examples/next14-app
3pnpm install
4pnm run dev

Then open http://localhost:3000/api-doc or http://localhost:3000/ on your browser

Linter

In order to set an eslint rule that checks that all the APIs actually have a swagger JsDoc description we can use the following settings:

Install the JsDoc eslint plugin:

1yarn add -D eslint-plugin-jsdoc

Create the custom rule in your eslint configuration file:

1{
2    //...your configuration
3    "overrides": [
4        //...your overrides
5        {
6            // Force the setting of a swagger description on each api endpoint
7            "files": ["pages/api/**/*.ts"],
8            "plugins": ["jsdoc"],
9            "rules": {
10                "jsdoc/no-missing-syntax": [
11                "error",
12                {
13                    "contexts": [
14                    {
15                        "comment": "JsdocBlock:has(JsdocTag[tag=swagger])",
16                        "context": "any",
17                        "message": "@swagger documentation is required on each API. Check this out for syntax info: https://github.com/jellydn/next-swagger-doc"
18                    }
19                    ]
20                }
21            ]
22        }
23    ]
24}

Pre-commit hook

This project uses pre-commit to enforce code quality. To install pre-commit hooks, run:

1pre-commit install

Author

👤 Huynh Duc Dung

• Website: https://productsway.com/
• Twitter: @jellydn
• Github: @jellydn

Stargazers

Show your support

Give a ⭐️ if this project helped you!

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Dung Duc Huynh (Kaka) 💻 📖	tmirkovic 📖	Matthew Holloway 💻	leventemihaly 📖	PAHRIZAL MA'RUP 💻	Aris 📖	Valerio Ageno 📖
cachho 💻

This project follows the all-contributors specification. Contributions of any kind welcome!