Onderwerp

Om Swagger te integreren met een Next.js applicatie, moet u Swagger gebruiken om uw API-routes te documenteren. Dit kan met name handig zijn voor het maken van een uitgebreide, zelfbeschrijvende API-documentatie die ontwikkelaars gemakkelijk kunnen volgen.

Hier is een stapsgewijze handleiding voor het instellen van Swagger in een Next.js-applicatie:

Stap 1: Installeer de benodigde pakketten

Installeer eerst de vereiste pakketten: swagger-jsdoc en swagger-ui-express.

npm install swagger-jsdoc swagger-ui-express

Stap 2: Swagger configureren

Maak een Swagger-configuratiebestand, swagger.js, in de hoofdmap van uw project of een geschikte map:

// swagger.js
const swaggerJSDoc = require('swagger-jsdoc');

const swaggerDefinition = {
  openapi: '3. 0. 0',
  info: {
    title: 'Next.js Swagger API',
    version: '1. 0. 0',
    description: 'API documentation using Swagger for a Next.js application',
  },
  servers: [
    {
      url: 'http://localhost:3000/api',
    },
  ],
};

const options = {
  swaggerDefinition,
  apis: ['./pages/api/*. js'], // Path to the API docs
};

const swaggerSpec = swaggerJSDoc(options);

module.exports = swaggerSpec;

Stap 3: Maak de Swagger UI-route

Maak vervolgens een nieuwe API-route in Next.js om de Swagger-gebruikersinterface te bedienen.

Voorbeeld: Maak een nieuw bestand pages/api/docs.js:

// pages/api/docs.js
import { withApiAuthRequired } from '@auth0/nextjs-auth0';
import swaggerUi from 'swagger-ui-express';
import swaggerSpec from '../../swagger';

const handler = async (req, res) => {
  swaggerUi.setup(swaggerSpec)(req, res);
};

export default withApiAuthRequired(handler);

// middleware to handle swagger
export const config = {
  api: {
    bodyParser: false,
  },
};

Stap 4: Voeg API-documentatieopmerkingen toe

Voeg JSDoc-opmerkingen toe aan uw API-eindpunten in pages/api/.

Voorbeeld: pages/api/example.js:

/**
 * @swagger
 * /example:
 *   get:
 *     description: This is an example endpoint
 *     responses:
 *       200:
 *         description: Returns a success message.
 */

export default function handler(req, res) {
  res.status(200). json({ message: 'Success' });
}

Stap 5: Toegang tot documentatie

Voer uw Next.js-toepassing uit en navigeer naar http://localhost:3000/api/docs om toegang te krijgen tot de Swagger-gebruikersinterface en uw API-documentatie te bekijken.

Voorbeeld bestandsstructuur

Hier is een vereenvoudigde bestandsstructuur voor uw Next.js project met Swagger:

.
├── pages
│   ├── api
│   │   ├── docs.js
│   │   └── example.js
├── swagger.js
└── package.json

Conclusie

Met deze stappen heb je Swagger met succes geïntegreerd in je Next.js applicatie. Deze opzet biedt een duidelijke en interactieve interface voor uw API-documentatie, waardoor het voor ontwikkelaars gemakkelijker wordt om uw API's te begrijpen en te gebruiken.

Het integreren van Swagger met een Next.js applicatie met behulp van de app-router omvat een paar extra stappen. Hier leest u hoe u dit kunt bereiken:

Stap 1: Installeer de benodigde pakketten

Eerst moet u de vereiste pakketten installeren: swagger-jsdoc en swagger-ui-express.

npm install swagger-jsdoc swagger-ui-express

Stap 2: Swagger configureren

Maak een Swagger-configuratiebestand, swagger.js, in de hoofdmap van uw project of een geschikte map:

// swagger.js
const swaggerJSDoc = require('swagger-jsdoc');

const swaggerDefinition = {
  openapi: '3. 0. 0',
  info: {
    title: 'Next.js Swagger API',
    version: '1. 0. 0',
    description: 'API documentation using Swagger for a Next.js application',
  },
  servers: [
    {
      url: 'http://localhost:3000/api',
    },
  ],
};

const options = {
  swaggerDefinition,
  apis: ['./app/api/**/*. js'], // Path to the API docs
};

const swaggerSpec = swaggerJSDoc(options);

module.exports = swaggerSpec;

Stap 3: Maak de Swagger UI-route

Maak vervolgens een nieuwe API-route in Next.js om de Swagger-gebruikersinterface te bedienen.

Voorbeeld: Maak een nieuw bestand app/api/docs/route.js:

// app/api/docs/route.js
import { NextResponse } from 'next/server';
import swaggerUi from 'swagger-ui-express';
import swaggerSpec from '../../../swagger';

export async function GET(req, res) {
  return await swaggerUi.setup(swaggerSpec, {
    swaggerOptions: {
      url: req.url,
    },
  })(req, res);
}

export const config = {
  api: {
    bodyParser: false,
  },
};

Stap 4: Voeg API-documentatieopmerkingen toe

Voeg JSDoc-opmerkingen toe aan uw API-eindpunten. Zorg ervoor dat al uw API-eindpunten correct zijn geannoteerd met JSDoc-opmerkingen.

Voorbeeld: app/api/example/route.js:

/**
 * @swagger
 * /example:
 *   get:
 *     description: This is an example endpoint
 *     responses:
 *       200:
 *         description: Returns a success message.
 */

export async function GET(req, res) {
  res.status(200). json({ message: 'Success' });
  return NextResponse.json({ message: 'Success' });
}

Stap 5: Toegang tot documentatie

Voer uw Next.js-toepassing uit en navigeer naar http://localhost:3000/api/docs om toegang te krijgen tot de Swagger-gebruikersinterface en uw API-documentatie te bekijken.

Voorbeeld bestandsstructuur

Hier is een vereenvoudigde bestandsstructuur voor uw Next.js project met Swagger geïntegreerd:

.
├── app
│   ├── api
│   │   ├── docs
│   │   │   └── route.js
│   │   └── example
│   │       └── route.js
├── swagger.js
└── package.json

Conclusie

Met deze stappen heb je Swagger met succes geïntegreerd in je Next.js applicatie met behulp van de app-router. Deze opzet biedt een duidelijke en interactieve interface voor uw API-documentatie, waardoor het voor ontwikkelaars gemakkelijker wordt om uw API's te begrijpen en te gebruiken.