next swagger doc
v0.4.0
Générez Swagger JSON API à partir des routes API NextJS
Si vous aimez travailler avec Next-sagger-doc, vous allez adorer les validations suivantes: Validations API NextJS, soutenez Zod, Yup, Validator le plus rapide, Joi, et plus
Ce package lit votre code source annoté par JSDOC sur la route de l'API NextJS et génère une spécification OpenAPI (Swagger).
NextJS + Swagger-jsdoc = next-sagger-doc
yarn add next-swagger-doc Pour incorporer next-swagger-doc avec votre projet Next.js 13, suivez ces étapes. Cette configuration générera une documentation de fanfaronnade pour votre API en fonction de votre code et fournira une interface utilisateur de fanfaronnade intégrée pour consulter la documentation.
Ensuite, créez un nouveau fichier lib/swagger.ts . Ce fichier utilise la bibliothèque next-swagger-doc pour créer une spécification Swagger basée sur les routes API dans votre projet Next.js.
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 ;
} ; Générez un nouveau fichier nommé app/api-doc/react-swagger.tsx . Dans ce fichier, créez et exportez un composant React qui utilise la bibliothèque swagger-ui-react pour rendre l'interface utilisateur Swagger en fonction de la spécification fournie.
À des fins de démonstration, voici un exemple utilisant Swagger-Ui-React
N'hésitez pas à utiliser toute autre bibliothèque d'interface utilisateur de fanfaronnade, comme Stoplightio / Elements. J'ai ajouté un exemple en utilisant cette bibliothèque dans le dossier 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 ; Créez une nouvelle app/api-doc/page.tsx . Cette page importe la spécification Swagger et le composant d'interface utilisateur Swagger pour afficher la documentation 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 >
) ;
} Enfin, ajoutez un commentaire Swagger à votre route API dans app/api/hello/route.ts . Ce commentaire comprend des métadonnées sur le point de terminaison de l'API qui sera lue par next-swagger-doc et incluse dans la spécification de 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 ,
} ) ;
} Maintenant, accédez à localhost:3000/api-doc (ou où que vous hébergez votre application Next.js), et vous devriez voir l'interface utilisateur de Swagger.
yarn add next-swagger-doc swagger-ui-reactpages/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 ; 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 ( ) ;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 ;next-swagger-doc.json {
"apiFolder" : " pages/api " ,
"schemaFolders" : [ " models " ],
"definition" : {
"openapi" : " 3.0.0 " ,
"info" : {
"title" : " Next Swagger API Example " ,
"version" : " 1.0 "
}
}
}yarn next-swagger-doc-cli next-swagger-doc.jsongh repo clone jellydn/next-swagger-doc
cd examples/next14-app
pnpm install
pnm run dev Puis ouvrez http: // localhost: 3000 / api-doc ou http: // localhost: 3000 / sur votre navigateur 
Afin de définir une règle Eslint qui vérifie que toutes les API ont réellement une description JSDOC de Swagger, nous pouvons utiliser les paramètres suivants:
Installez le plugin JSDOC Eslint:
yarn add -D eslint-plugin-jsdocCréez la règle personnalisée dans votre fichier de configuration Eslint:
{
//...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 "
}
]
}
]
}
]
}Ce projet utilise le pré-engagement pour appliquer la qualité du code. Pour installer des crochets pré-Commiss, exécuter:
pre-commit install? Huynh Duc Dung
Donnez un ️ si ce projet vous a aidé!
Merci à ces gens merveilleux (clé emoji):
Dung Duc Huynh (Kaka) | tmirkovic | Matthew Holloway | leventihaly | Pahrizal Ma'rup | Aris | Valerio Ageno |
cachho |
Ce projet suit les spécifications de tous les contributeurs. Contributions de toute nature bienvenue!
