Using Swagger with Next.js

Question

Using Swagger with Next.js

Is it possible to generate Swagger documentation for API routes in NEXT.js? I am working with Next.js for both front-end and back-end tasks, and I am interested in creating a Swagger documentation for the APIs implemented in Next.js.

javascript swagger next.js

Answer 1

Answer №1

If you're looking to streamline the integration between Next.js and Swagger, check out this project:

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

import { GetStaticProps, InferGetStaticPropsType } from 'next';

import { createSwaggerSpec } from 'next-swagger-doc';
import SwaggerUI from 'swagger-ui-react';
import 'swagger-ui-react/swagger-ui.css';

const ApiDoc = ({ spec }: InferGetStaticPropsType<typeof getStaticProps>) => {
  return <SwaggerUI spec={spec} />;
};

export const getStaticProps: GetStaticProps = async ctx => {
  const spec: Record<string, any> = createSwaggerSpec({
    title: 'NextJS Swagger',
    version: '0.1.0',
  });
  return { props: { spec } };
};

export default ApiDoc;

This is how a Next.js API route endpoint is defined:

/**
 * @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',
  });
};

Answer 2

If you're looking to streamline the integration between Next.js and Swagger, check out this project:

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

import { GetStaticProps, InferGetStaticPropsType } from 'next';

import { createSwaggerSpec } from 'next-swagger-doc';
import SwaggerUI from 'swagger-ui-react';
import 'swagger-ui-react/swagger-ui.css';

const ApiDoc = ({ spec }: InferGetStaticPropsType<typeof getStaticProps>) => {
  return <SwaggerUI spec={spec} />;
};

export const getStaticProps: GetStaticProps = async ctx => {
  const spec: Record<string, any> = createSwaggerSpec({
    title: 'NextJS Swagger',
    version: '0.1.0',
  });
  return { props: { spec } };
};

export default ApiDoc;

This is how a Next.js API route endpoint is defined:

/**
 * @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',
  });
};

Answer 3

Answer №2

I created a handy npm library that automatically generates Swagger documentation from your NextJS project without requiring any user input!

Although it's still in the early Beta stage, I hope you find it helpful. https://www.npmjs.com/package/nextjs-routes-docs

To use, simply execute

npx nextjs-routes-docs [dir]

Answer 4

I created a handy npm library that automatically generates Swagger documentation from your NextJS project without requiring any user input!

Although it's still in the early Beta stage, I hope you find it helpful. https://www.npmjs.com/package/nextjs-routes-docs

To use, simply execute

npx nextjs-routes-docs [dir]

Answer 5

Answer №3

It's essential to have the swagger json files or specification for the APIs and utilize libraries like Swagger UI or Redoc

By using Redoc, you can implement a /doc/[slug].js to dynamically fetch the .json or yaml files for your documentation (or swagger ui)

This page: , offers an array of tools for React and OpenAPI in general that are worth exploring.

Answer 6

It's essential to have the swagger json files or specification for the APIs and utilize libraries like Swagger UI or Redoc

By using Redoc, you can implement a /doc/[slug].js to dynamically fetch the .json or yaml files for your documentation (or swagger ui)

This page: , offers an array of tools for React and OpenAPI in general that are worth exploring.

Answer 7

Answer №4

To implement this feature, follow these steps after annotating your route.js files with JSDoc ie. @swagger in NextJS 13.

Step 1.

Start by installing the necessary dependencies:

npm i swagger-ui-react swagger-jsdocs

Step 2.

Next, create a component file named src/components/swagger-doc.jsx to display the Swagger documentation using swagger-ui-react

'use client';

// Import Modules
import PropTypes from 'prop-types';

// Import Components
import SwaggerUI from 'swagger-ui-react';

// Import Miscs
import 'swagger-ui-react/swagger-ui.css';

const SwaggerDoc = ({ spec }) => (
  <SwaggerUI spec={spec} />
);

SwaggerDoc.propTypes = {
  /**
   * OpenApi specifications
   */
  spec: PropTypes.oneOfType([PropTypes.object]).isRequired,
};

export default SwaggerDoc;

Step 3.

Create a configuration file called src/configs.js where you define options for swagger-jsdocs

const CONFIG = {
  jsDocs: {
    apis: ['**/api/v1/**/route.js'],
    swaggerDefinition: {
      info: {
        title: 'Some Service',
        version: '0.0.1',
        description: 'This is an API doc for Some Service.',
      },
    },
  },
};

export default CONFIG;

Step 4.

Now, set up a /docs route by creating src/app/docs/page.jsx

// Import Modules
import swaggerJsdoc from 'swagger-jsdoc';

// Import Components
import SwaggerDoc from '../../components/swagger-doc';

// Import Miscs
import CONFIG from '../../configs';

const getData = async () => {
  const spec = swaggerJsdoc(CONFIG.jsDocs);

  return spec;
};

const Docs = async () => {
  const data = await getData();

  return <SwaggerDoc spec={data} />;
};

export default Docs;

Note: For detailed configurations of the dependencies, refer to the following links:

swagger-jsdoc swagger-ui-react

Answer 8

To implement this feature, follow these steps after annotating your route.js files with JSDoc ie. @swagger in NextJS 13.

Step 1.

Start by installing the necessary dependencies:

npm i swagger-ui-react swagger-jsdocs

Step 2.

Next, create a component file named src/components/swagger-doc.jsx to display the Swagger documentation using swagger-ui-react

'use client';

// Import Modules
import PropTypes from 'prop-types';

// Import Components
import SwaggerUI from 'swagger-ui-react';

// Import Miscs
import 'swagger-ui-react/swagger-ui.css';

const SwaggerDoc = ({ spec }) => (
  <SwaggerUI spec={spec} />
);

SwaggerDoc.propTypes = {
  /**
   * OpenApi specifications
   */
  spec: PropTypes.oneOfType([PropTypes.object]).isRequired,
};

export default SwaggerDoc;

Step 3.

Create a configuration file called src/configs.js where you define options for swagger-jsdocs

const CONFIG = {
  jsDocs: {
    apis: ['**/api/v1/**/route.js'],
    swaggerDefinition: {
      info: {
        title: 'Some Service',
        version: '0.0.1',
        description: 'This is an API doc for Some Service.',
      },
    },
  },
};

export default CONFIG;

Step 4.

Now, set up a /docs route by creating src/app/docs/page.jsx

// Import Modules
import swaggerJsdoc from 'swagger-jsdoc';

// Import Components
import SwaggerDoc from '../../components/swagger-doc';

// Import Miscs
import CONFIG from '../../configs';

const getData = async () => {
  const spec = swaggerJsdoc(CONFIG.jsDocs);

  return spec;
};

const Docs = async () => {
  const data = await getData();

  return <SwaggerDoc spec={data} />;
};

export default Docs;

Note: For detailed configurations of the dependencies, refer to the following links:

swagger-jsdoc swagger-ui-react

Answer 9

Answer №5

If you're looking for a way to automatically generate OpenAPI specification files from your API routes, consider checking out Next REST Framework: https://github.com/blomqma/next-rest-framework

Answer 10

If you're looking for a way to automatically generate OpenAPI specification files from your API routes, consider checking out Next REST Framework: https://github.com/blomqma/next-rest-framework

Using Swagger with Next.js

Answer №1

Answer №2

Answer №3

Answer №4

Answer №5

Similar questions

Are Viewmodel contents empty after ajax request?

Renaming form elements using JQuery's .load method

AngularJS is not responding to a 400 bad request

Display/Conceal JavaScript

Adding color between lines in Three.js

A tutorial on how to create the appearance of disabled buttons that look the same as enabled buttons through the use

Having trouble with NVM not working correctly in Ubuntu 21.04 Terminal?

What causes the sudden change in value of this array?

Customize React JS Material UI's InputBase to be responsive

Leveraging GSAP and Vue by utilizing props to dynamically calculate a maxWidth

Difficulty encountered while connecting JSON data to a list using Angular JS

Looking to align the labels of material UI tabs to the left instead of their default center alignment? Here's how

What is the best way to specify a submission destination for a custom form component in Vue?

Error message: ReactJs is throwing a TypeError due to mod not being recognized as a function

React and SASS - issue with checkbox component not being properly aligned with its label

Issue with handling keypress event and click event in Internet Explorer

NodeJS video streaming feature does not close the connection when the user disconnects or navigates to a different page

Tips for Choosing the Right Objects in Vue.js

How does the pound sign (#) signal the beginning of a comment in JavaScript?

Issue with checkboxes preventing submission of form