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

Understanding how to parse an array of arrays in JavaScript can be a

Exploring ways to access data stored in interconnected models, such as MongoDB and NodeJS

Transform an array of strings into an array of floating point numbers using AngularJS

Using AngularJS to transfer data from a datepicker to an ng-model

Unexpected issue: Ajax success function not displaying anything in the console

I am attempting to retrieve the initial three results from my MySQL database using Node.js, but I keep encountering an error

How to programmatically unselect an ng-checkbox in AngularJS when it is removed from an array

`Save user edits on the webpage using Electron`

Ways to verify if a Discord.js snowflake is present in a collection of other identification numbers

Can you choose and generate identical values using react-select?

eliminating parameters in URL for redirection in Next.js

Tips for modifying JSON property names during the parsing process

Is there a method to prevent data loss on page refresh by persisting data stored in a database?

Identify the mouse's location in relation to its parent element, not the entire webpage

Numerals for Central Leaflet Marker

JavaScript Object Featuring a Default Function Along with Additional Functions

Addressing the issue of prolonged Electron initialization

Using the DatePicker component with non-escaped Latin alphabet characters in date-fns for ReactJS

Could Ramda assist in enhancing pipeline/composition processes with a logging feature?

Insert a div element into the JavaScript file