next swagger doc next swagger doc

Willkommen bei Next-Swagger-Doc

Generieren Sie die Prahlerei -JSON -API von NextJs API Routen

_{Wenn Sie gerne mit Next-Swagger-Doc zusammenarbeiten, werden Sie die nächsten Validationen lieben: NEXTJS-API-Validierungen, Unterstützen Sie Zod, Yup, schnellste Validator, Joi und mehr}

? Homepage

Demo

Voraussetzungen

NextJS> = 9
Knoten> = 18

Motivation

Dieses Paket liest Ihren JSDOC-ankündigten Quellcode auf der NextJS-API-Route und generiert eine OpenAPI-Spezifikation (Swagger).

NextJS + Swagger-JSDOC = NEXT-SWAGGE-DOC

Installieren

yarn add next-swagger-doc

Verwendung Nr. 1: Nächster Swagger-Doc mit Next.js 13

Um next-swagger-doc mit Ihrem nächsten Projekt zu integrieren, befolgen Sie diese Schritte. Dieses Setup generiert Swagger-Dokumentation für Ihre API basierend auf Ihrem Code und bietet eine integrierte SWAGGE-Benutzeroberfläche zum Anzeigen der Dokumentation.

1. Erstellen Sie die Wirkungsspezifikation

Erstellen Sie als Nächstes eine neue Datei lib/swagger.ts . Diese Datei verwendet die next-swagger-doc -Bibliothek, um eine Swagger-Spezifikation basierend auf den API-Routen in Ihrem nächsten.js-Projekt zu erstellen.

 import { createSwaggerSpec } from "next-swagger-doc" ;

export const getApiDocs = async ( ) => {
  const spec = createSwaggerSpec ( {
    apiFolder : "app/api" , // define api folder under app folder
    definition : {
      openapi : "3.0.0" ,
      info : {
        title : "Next Swagger API Example" ,
        version : "1.0" ,
      } ,
      components : {
        securitySchemes : {
          BearerAuth : {
            type : "http" ,
            scheme : "bearer" ,
            bearerFormat : "JWT" ,
          } ,
        } ,
      } ,
      security : [ ] ,
    } ,
  } ) ;
  return spec ;
} ;

2. Erstellen Sie Prahlerei -UI -Komponente

Generieren Sie eine neue Datei mit dem Namen app/api-doc/react-swagger.tsx . Erstellen und exportieren Sie in dieser Datei eine React-Komponente, die die swagger-ui-react Reaktionsbibliothek verwendet, um die Swagger-Benutzeroberfläche gemäß der angegebenen Spezifikation zu rendern.

Zu Demonstrationszwecken finden Sie ein Beispiel mit Swagger-UI-Reaktionen

Nehmen Sie eine alternative Swagger UI -Bibliothek wie Stoplightio/Elemente an. Ich habe ein Beispiel mit dieser Bibliothek im example hinzugefügt.

 'use client' ;

import SwaggerUI from 'swagger-ui-react' ;
import 'swagger-ui-react/swagger-ui.css' ;

type Props = {
  spec : Record < string , any > ,
} ;

function ReactSwagger ( { spec } : Props ) {
  return < SwaggerUI spec = { spec } /> ;
}

export default ReactSwagger ;

3. Erstellen Sie die API -Dokumentationsseite

Erstellen Sie eine neue Datei app/api-doc/page.tsx . Diese Seite importiert die Swagger -Spezifikation und die Swagger UI -Komponente, um die Dokumentation der Prahlerei anzuzeigen.

 import { getApiDocs } from "@/lib/swagger" ;
import ReactSwagger from "./react-swagger" ;

export default async function IndexPage ( ) {
  const spec = await getApiDocs ( ) ;
  return (
    < section className = "container" >
      < ReactSwagger spec = { spec } />
    </ section >
  ) ;
}

V.

Fügen Sie zuletzt einen Swagger -Kommentar zu Ihrer API -Route in app/api/hello/route.ts hinzu. Dieser Kommentar enthält Metadaten über den API-Endpunkt, der von next-swagger-doc gelesen und in der Swagger-Spezifikation aufgenommen wird.

 /**
 * @swagger
 * /api/hello:
 *   get:
 *     description: Returns the hello world
 *     responses:
 *       200:
 *         description: Hello World!
 */
export async function GET ( _request : Request ) {
  // Do whatever you want
  return new Response ( 'Hello World!' , {
    status : 200 ,
  } ) ;
}

Navigieren Sie nun zu localhost:3000/api-doc (oder wo immer Sie Ihre nächste Anwendung von.js bewerben), und Sie sollten die UI der Prahlerei sehen.

Verwendung Nr. 2: Erstellen Sie eine einzelne API -Dokument

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

Erstellen Sie eine Live-Swagger-Seite, z. pages/api-doc.tsx

 import { GetStaticProps , InferGetStaticPropsType } from 'next' ;
import { createSwaggerSpec } from 'next-swagger-doc' ;
import dynamic from 'next/dynamic' ;
import 'swagger-ui-react/swagger-ui.css' ;

const SwaggerUI = dynamic < {
  spec : any ;
} > ( import ( 'swagger-ui-react' ) , { ssr : false } ) ;

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

export const getStaticProps : GetStaticProps = async ( ) => {
  const spec : Record < string , any > = createSwaggerSpec ( {
    apiFolder : 'pages/api' // or 'src/pages/api',
    definition : {
      openapi : '3.0.0' ,
      info : {
        title : 'Next Swagger API Example' ,
        version : '1.0' ,
      } ,
    } ,
  } ) ;

  return {
    props : {
      spec ,
    } ,
  } ;
} ;

export default ApiDoc ;

Verwendung Nr. 3: Verwenden Sie die API -Route für die NextJS, um die SWAGVE JSON Spec zu erstellen

Schritt 1: Erstellen Sie eine API -Route auf NextJs, z. B. pages/api/doc.ts

 import { withSwagger } from "next-swagger-doc" ;

const swaggerHandler = withSwagger ( {
  definition : {
    openapi : "3.0.0" ,
    info : {
      title : "NextJS Swagger" ,
      version : "0.1.0" ,
    } ,
  } ,
  apiFolder : "pages/api" ,
} ) ;
export default swaggerHandler ( ) ;

Schritt 2: Fügen Sie JSDOC zu allen NextJs -API -Routen hinzu, zum Beispiel: pages/api/hello.ts

 import { NextApiRequest , NextApiResponse } from "next" ;

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

export default handler ;

Schritt 3: Greifen Sie auf das Swagger API -Dokument zu

Verwendung Nr. 4: Swagger -Datei von CLI generieren

Schritt 1: Erstellen Sie eine JSON-Konfigurationsdatei als next-swagger-doc.json

{
  "apiFolder" : " pages/api " ,
  "schemaFolders" : [ " models " ],
  "definition" : {
    "openapi" : " 3.0.0 " ,
    "info" : {
      "title" : " Next Swagger API Example " ,
      "version" : " 1.0 "
    }
  }
}

Schritt 2: Führen Sie die CLI für die Generierung der Swagger -Datei aus

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

Beispiel App ausführen

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

Öffnen Sie dann http: // localhost: 3000/api-doc oder http: // localhost: 3000/auf Ihrem Browser ./example-screenshot.png

Linter

Um eine Eslint -Regel festzulegen, die überprüft, ob alle APIs tatsächlich eine Prahlerei -JSDOC -Beschreibung haben, können wir die folgenden Einstellungen verwenden:

Installieren Sie das JSDOC Eslint -Plugin:

yarn add -D eslint-plugin-jsdoc

Erstellen Sie die benutzerdefinierte Regel in Ihrer Eslint -Konfigurationsdatei:

{
    //...your configuration
    "overrides" : [
        //...your overrides
        {
            // Force the setting of a swagger description on each api endpoint
            "files" : [ " pages/api/**/*.ts " ],
            "plugins" : [ " jsdoc " ],
            "rules" : {
                "jsdoc/no-missing-syntax" : [
                " error " ,
                {
                    "contexts" : [
                    {
                        "comment" : " JsdocBlock:has(JsdocTag[tag=swagger]) " ,
                        "context" : " any " ,
                        "message" : " @swagger documentation is required on each API. Check this out for syntax info: https://github.com/jellydn/next-swagger-doc "
                    }
                    ]
                }
            ]
        }
    ]
}

Pre-Commit-Haken

In diesem Projekt werden die Codequalität durch die Durchsetzung der Code-Qualität verwendet. Ausführen von Vorkommiten, um Vorkommende zu installieren: