next swagger doc

Selamat datang di Next-Spagger-Doc

Hasilkan Swagger JSON API dari rute API NEXTJS

_{Jika Anda menikmati bekerja dengan next-wawgagger-doc, Anda akan menyukai validasi berikutnya: validasi API nextJS, mendukung zod, yup, validator tercepat, joi, dan banyak lagi}

? Beranda

Demo

Prasyarat

• Nextjs> = 9
• Node> = 18

Motivasi

Paket ini membaca kode sumber yang dianotasi JSDOC Anda pada rute API NEXTJS dan menghasilkan spesifikasi OpenAPI (Swagger).

nextjs + swagger-jsdoc = next-spwagger-doc

Memasang

yarn add next-swagger-doc

Penggunaan #1: Next-Swagger-Doc dengan Next.js 13

Untuk menggabungkan next-swagger-doc dengan proyek berikutnya. JS 13 Anda, ikuti langkah-langkah ini. Pengaturan ini akan menghasilkan dokumentasi Swagger untuk API Anda berdasarkan kode Anda dan memberikan UI Swagger bawaan untuk melihat dokumentasi.

1. Buat spesifikasi Swagger

Selanjutnya, buat file baru lib/swagger.ts . File ini menggunakan perpustakaan next-swagger-doc untuk membuat spesifikasi Swagger berdasarkan rute API di proyek berikutnya.js Anda.

 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. Buat komponen UI Swagger

Hasilkan file baru bernama app/api-doc/react-swagger.tsx . Dalam file ini, buat dan ekspor komponen bereaksi yang memanfaatkan perpustakaan swagger-ui-react untuk membuat UI Swagger sesuai dengan spesifikasi yang disediakan.

Untuk tujuan demonstrasi, berikut adalah contoh menggunakan Swagger-ui-react

Jangan ragu untuk menggunakan perpustakaan UI Swagger alternatif apa pun, seperti stoplioo/elemen. Saya telah menambahkan contoh menggunakan pustaka ini di folder example .

 '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. Buat halaman dokumentasi API

Buat app/api-doc/page.tsx . Halaman ini mengimpor spesifikasi Swagger dan komponen UI Swagger untuk menampilkan dokumentasi Swagger.

 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 >
  ) ;
}

4. Tambahkan komentar kesombongan ke rute API

Terakhir, tambahkan komentar Swagger ke rute API Anda di app/api/hello/route.ts . Komentar ini mencakup metadata tentang titik akhir API yang akan dibaca oleh next-swagger-doc dan termasuk dalam spesifikasi Swagger.

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

Sekarang, navigasikan ke localhost:3000/api-doc (atau di mana pun Anda meng-host aplikasi Next.js Anda), dan Anda akan melihat UI Swagger.

Penggunaan #2: Buat satu dokumen API tunggal

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

• Buat halaman Live Swagger, misalnya: 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 ; 

Penggunaan #3: Gunakan rute API NextJS untuk membuat spesifikasi JSON Swagger

• Langkah 1: Buat rute API di NextJS, misalnya: 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 ( ) ;

• Langkah 2: Tambahkan JSDOC ke rute API NextJS, misalnya: 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 ;

• Langkah 3: Akses Dokter API Swagger

Penggunaan #4: Hasilkan file Swagger dari CLI

• Langkah 1: Buat file konfigurasi JSON sebagai next-swagger-doc.json

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

• Langkah 2: Jalankan CLI untuk menghasilkan file Swagger

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

Jalankan aplikasi contoh

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

Kemudian buka http: // localhost: 3000/API-doc atau http: // localhost: 3000/di browser Anda

Linter

Untuk menetapkan aturan Eslint yang memeriksa bahwa semua API benar -benar memiliki deskripsi JSDOC Swagger kita dapat menggunakan pengaturan berikut:

Instal plugin JSDOC ESLINT:

yarn add -D eslint-plugin-jsdoc

Buat aturan khusus di file konfigurasi Eslint Anda:

{
    //...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 "
                    }
                    ]
                }
            ]
        }
    ]
}

Hook pra-komit

Proyek ini menggunakan pra-komit untuk menegakkan kualitas kode. Untuk memasang kait pra-komit, jalankan:

pre-commit install

Pengarang

? Huynh Duc Dung

• Situs web: https://productsway.com/
• Twitter: @jellydn
• GitHub: @jellydn

Stargazer

Tunjukkan dukungan Anda

Berikan ️ jika proyek ini membantu Anda!

Kontributor

Terima kasih kepada orang -orang yang luar biasa ini (Kunci Emoji):

Dung Duc Huynh (Kaka)	tmirkovic	Matthew Holloway	Leventemihaly	Pahrizal Ma'rup	ARIS	Valerio Ageno
Cachho

Proyek ini mengikuti spesifikasi semua-kontributor. Kontribusi apa pun yang baik!