Thema

Um Swagger in eine Next.js Anwendung zu integrieren, sollten Sie Swagger verwenden, um Ihre API-Routen zu dokumentieren. Dies kann besonders nützlich sein, um eine umfassende, selbstbeschreibende API-Dokumentation zu erstellen, der Entwickler leicht folgen können.

Hier ist eine Schritt-für-Schritt-Anleitung zum Einrichten von Swagger in einer Next.js Anwendung:

Schritt 1: Installieren Sie die erforderlichen Pakete

Installieren Sie zunächst die erforderlichen Pakete: swagger-jsdoc und swagger-ui-express.

npm install swagger-jsdoc swagger-ui-express

Schritt 2: Swagger konfigurieren

Erstellen Sie eine Swagger-Konfigurationsdatei, swagger.js, in Ihrem Projektstammverzeichnis oder in einem geeigneten Verzeichnis:

// 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;

Schritt 3: Erstellen der Swagger-UI-Route

Erstellen Sie als Nächstes eine neue API-Route in Next.js, um die Swagger-Benutzeroberfläche bereitzustellen.

Beispiel: Erstellen Sie eine neue Datei 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,
  },
};

Schritt 4: API-Dokumentationskommentare hinzufügen

Fügen Sie JSDoc-Kommentare zu Ihren API-Endpunkten in pages/api/ hinzu.

Beispiel: 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' });
}

Schritt 5: Zugriff auf die Dokumentation

Führen Sie Ihre Next.js Anwendung aus, und navigieren Sie zu http://localhost:3000/api/docs, um auf die Swagger-Benutzeroberfläche zuzugreifen und Ihre API-Dokumentation anzuzeigen.

Beispiel für eine Dateistruktur

Hier ist eine vereinfachte Dateistruktur für Ihr Next.js Projekt mit Swagger:

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

Fazit

Mit diesen Schritten haben Sie Swagger erfolgreich in Ihre Next.js Anwendung integriert. Dieses Setup bietet eine übersichtliche und interaktive Schnittstelle für Ihre API-Dokumentation, die es Entwicklern erleichtert, Ihre APIs zu verstehen und zu verwenden.

Die Integration von Swagger in eine Next.js Anwendung mithilfe des App-Routers erfordert einige zusätzliche Schritte. So können Sie dies erreichen:

Schritt 1: Installieren Sie die erforderlichen Pakete

Zuerst müssen Sie die erforderlichen Pakete installieren: swagger-jsdoc und swagger-ui-express.

npm install swagger-jsdoc swagger-ui-express

Schritt 2: Swagger konfigurieren

Erstellen Sie eine Swagger-Konfigurationsdatei, swagger.js, in Ihrem Projektstammverzeichnis oder in einem geeigneten Verzeichnis:

// 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;

Schritt 3: Erstellen der Swagger-UI-Route

Erstellen Sie als Nächstes eine neue API-Route in Next.js, um die Swagger-Benutzeroberfläche bereitzustellen.

Beispiel: Erstellen Sie eine neue Datei 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,
  },
};

Schritt 4: API-Dokumentationskommentare hinzufügen

Fügen Sie JSDoc-Kommentare zu Ihren API-Endpunkten hinzu. Stellen Sie sicher, dass alle Ihre API-Endpunkte korrekt mit JSDoc-Kommentaren versehen sind.

Beispiel: 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' });
}

Schritt 5: Zugriff auf die Dokumentation

Führen Sie Ihre Next.js Anwendung aus, und navigieren Sie zu http://localhost:3000/api/docs, um auf die Swagger-Benutzeroberfläche zuzugreifen und Ihre API-Dokumentation anzuzeigen.

Beispiel für eine Dateistruktur

Hier ist eine vereinfachte Dateistruktur für Ihr Next.js Projekt mit integriertem Swagger:

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

Fazit

Mit diesen Schritten haben Sie Swagger mithilfe des App-Routers erfolgreich in Ihre Next.js-Anwendung integriert. Dieses Setup bietet eine übersichtliche und interaktive Schnittstelle für Ihre API-Dokumentation, die es Entwicklern erleichtert, Ihre APIs zu verstehen und zu verwenden.