next swagger doc
v0.4.0
Nextjs API 경로에서 Swagger JSON API를 생성합니다
Next-Swagger-DOC와 함께 일하는 것을 좋아한다면 차세대 검증을 좋아할 것입니다 : Nextjs API 검증, Zod, Yup, Fast-Validator, Joi 등을 지원합니다.
이 패키지는 NextJS API Route에서 JSDOC 공개 소스 코드를 읽고 OpenAPI (Swagger) 사양을 생성합니다.
Nextjs + Swagger-JSDOC = Next-Swagger-DOC
yarn add next-swagger-doc JS 13 프로젝트에 next-swagger-doc 통합하려면 다음 단계를 따르십시오. 이 설정은 코드를 기반으로 API에 대한 Swagger 문서를 생성하고 문서를 볼 수있는 내장 Swagger UI를 제공합니다.
다음으로 새 파일 lib/swagger.ts 만듭니다. 이 파일은 next-swagger-doc 라이브러리를 사용하여 다음.js 프로젝트의 API 경로를 기반으로 Swagger 사양을 만듭니다.
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 ;
} ; app/api-doc/react-swagger.tsx 라는 새 파일을 생성하십시오. 이 파일에서는 swagger-ui-react 라이브러리를 사용하여 제공된 사양에 따라 Swagger UI를 렌더링하는 React 구성 요소를 생성 및 내 보냅니다.
시연 목적으로, 여기 Swagger-Ui-React를 사용하는 예입니다
Scoundlightio/Elements와 같은 대체 Swagger UI 라이브러리를 자유롭게 사용하십시오. 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 ; 새 파일 app/api-doc/page.tsx 만듭니다. 이 페이지는 Swagger Spec 및 Swagger UI 구성 요소를 가져와 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 >
) ;
} 마지막으로 app/api/hello/route.ts 의 API Route에 Swagger 주석을 추가하십시오. 이 의견에는 next-swagger-doc 가 읽고 Swagger 사양에 포함될 API 엔드 포인트에 대한 메타 데이터가 포함됩니다.
/**
* @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 ,
} ) ;
} 이제 localhost:3000/api-doc (또는 다음에 다음 위치를 호스팅하는 곳)로 이동하면 Swagger UI가 표시됩니다.
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 그런 다음 브라우저에서 http : // localhost : 3000/api-doc 또는 http : // localhost : 3000을 엽니 다 
모든 API에 실제로 Swagger JSDOC 설명이 있는지 확인하는 eslint 규칙을 설정하려면 다음 설정을 사용할 수 있습니다.
JSDOC ESLINT 플러그인 설치 :
yarn add -D eslint-plugin-jsdoceslint 구성 파일에서 사용자 정의 규칙을 만듭니다.
{
//...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 install? Huynh Duc Dung
이 프로젝트가 도움이된다면 ️를주세요!
이 멋진 사람들에게 감사드립니다 (이모티콘 키) :
Dung Duc Huynh (카카) | Tmirkovic | Matthew Holloway | Leventemihaly | Pahrizal Ma'rup | 아리스 | 발레리오 아세노 |
Cachho |
이 프로젝트는 All-Contritors 사양을 따릅니다. 모든 종류의 공헌을 환영합니다!
