swagger ui express

Swagger UI Express

진술	가지	기능	윤곽

이 모듈을 사용하면 swagger.json 파일을 기반으로 Express에서 자동 생성 된 Swagger-UI 생성 API 문서를 제공 할 수 있습니다. 결과는 경로를 통해 API 서버에서 호스팅 된 API에 대한 살아있는 문서입니다.

Swagger 버전은 NPM 모듈 Swagger-UI-Dist에서 가져옵니다. 잠금 파일을 사용하거나 환경에서 일관되도록하려는 Swagger-UI-Dist 버전을 지정하십시오.

당신은 또한 다음에 관심이있을 수 있습니다.

• Swagger-JSDOC : JSDOC 주석으로 경로를 마크 업 할 수 있습니다. 그런 다음 전체 Swagger YML 구성을 동적으로 생성 하여이 모듈로 전달하여 문서를 작성할 수 있습니다. 자세한 내용은 사용 섹션의 아래를 참조하십시오.
• Swagger Tools : Swagger 편집기, Swagger Code Gen 등을 포함한 다양한 도구

용법

NPM을 사용하여 설치 :

$ npm install swagger-ui-express

Express Setup app.js

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument ) ) ;

또는 Express 라우터를 사용하는 경우

 const router = require ( 'express' ) . Router ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

router . use ( '/api-docs' , swaggerUi . serve ) ;
router . get ( '/api-docs' , swaggerUi . setup ( swaggerDocument ) ) ;

http : // <app_host> : <app_port> /api-docs를 브라우저에서 엽니 다.

Swagger Document Checkout Swagger-Express-Router를 기반으로 라우팅을 설정하려면

Swagger-jsdoc

Swagger-JSDOC를 사용하는 경우 Swaggerspec을 설정 함수로 전달합니다.

 // Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc ( options ) ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerSpec ) ) ;

Swagger Explorer

기본적으로 Swagger Explorer Bar는 숨겨져 있으며, 옵션의 '탐색기'속성으로 설정 기능을 전달합니다.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  explorer : true
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

맞춤형 스와 거 옵션

Swaggerui 클라이언트에게 validatorUrl에게 맞춤 옵션을 전달하려면 옵션의 'SwaggerOptions'속성으로 객체를 설정 함수로 전달합니다.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  swaggerOptions : {
    validatorUrl : null
  }
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

사용 가능한 모든 옵션은 Swagger UI 구성을 참조하십시오.

맞춤형 CSS 스타일

Swagger 페이지의 스타일을 사용자 정의하려면 사용자 정의 CSS를 옵션의 'CustomCSS'속성으로 설정 함수로 전달할 수 있습니다.

예를 들어 Swagger 헤더를 숨기려면 :

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCss : '.swagger-ui .topbar { display: none }'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

URL의 사용자 정의 CSS 스타일

URL을 사용자 정의 CSS 파일로 전달할 수도 있고 값은 파일의 공개 URL이어야하며 Swagger 경로에 상대적이거나 절대적 일 수 있습니다.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCssUrl : '/custom.css'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

여러 CSS 파일을로드하기 위해 CSS URL 배열을 전달할 수도 있습니다.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCssUrl : [
    '/custom.css' ,
    'https://example.com/other-custom.css'
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

맞춤 JS

HTML을 완전히 제어하려면 자신의 JavaScript 파일을 제공 할 수 있습니다. 값은 절대 또는 상대 경로를 허용합니다. 값은 JS 파일의 공개 URL이어야합니다.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJs : '/custom.js'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

여러 JS 파일을로드하기 위해 JS URL 배열을 전달할 수도 있습니다.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJs : [
    '/custom.js' ,
    'https://example.com/other-custom.js'
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

문자열 또는 배열로 인라인 JavaScript를 추가 할 수도 있습니다.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJsStr : 'console.log("Hello World")'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ; 

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJsStr : [
    'console.log("Hello World")' ,
    `
    var x = 1
    console.log(x)
    `
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

URL에서 Swagger를로드하십시오

문서를 주입하는 대신 URL에서 Swagger를로드하려면 null 첫 번째 매개 변수로 전달하고 상대 또는 절대 URL을 설정 기능에서 'SwaggerOptions'로 'URL'속성으로 전달하십시오.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;

var options = {
  swaggerOptions : {
    url : 'http://petstore.swagger.io/v2/swagger.json'
  }
}

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( null , options ) ) ;

Explorer Bar의 드롭 다운으로 URL의 여러 Swagger 문서를로드하려면 name 과 url 있는 객체 배열을 설정 기능에서 'SwaggerOptions'로 'URL'속성으로 전달하십시오.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;

var options = {
  explorer : true ,
  swaggerOptions : {
    urls : [
      {
        url : 'http://petstore.swagger.io/v2/swagger.json' ,
        name : 'Spec1'
      } ,
      {
        url : 'http://petstore.swagger.io/v2/swagger.json' ,
        name : 'Spec2'
      }
    ]
  }
}

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( null , options ) ) ;

설정 옵션에서 드롭 다운을 볼 수 있도록 'Explorer'옵션이 'True'로 설정되어 있는지 확인하십시오.

Yaml 파일에서 Swagger를로드하십시오

Swagger 사양을로드하려면 Yaml 파일을 사용하여 Yaml을 JSON으로 변환 할 수있는 모듈을 사용해야합니다. 예를 들어 yaml .

 npm install yaml

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const fs = require ( "fs" )
const YAML = require ( 'yaml' )

const file  = fs . readFileSync ( './swagger.yaml' , 'utf8' )
const swaggerDocument = YAML . parse ( file )

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument ) ) ;

로드하기 전에 Swagger 파일을 즉시 수정하십시오

들어오는 요청 객체를 기반으로 Swagger 파일에 호스트 또는 기타 컨텐츠를 동적으로 설정하려면 REQ 객체를 통해 JSON을 전달할 수 있습니다. 이를 달성하려면 Swagger JSON을 설정 함수로 전달하지 않으면 req 객체에서 swaggerDoc 찾습니다.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = { }

app . use ( '/api-docs' , function ( req , res , next ) {
    swaggerDocument . host = req . get ( 'host' ) ;
    req . swaggerDoc = swaggerDocument ;
    next ( ) ;
} , swaggerUi . serveFiles ( swaggerDocument , options ) , swaggerUi . setup ( ) ) ;

두 개의 swagger 문서

다른 Swagger 문서가있는 2 개의 Swagger UI 인스턴스를 실행하려면 Serve 기능 대신 Servfiles 기능을 사용하십시오. Servfiles 함수는 설정 함수와 동일한 시그니처를 갖습니다.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocumentOne = require ( './swagger-one.json' ) ;
const swaggerDocumentTwo = require ( './swagger-two.json' ) ;

var options = { }

app . use ( '/api-docs-one' , swaggerUi . serveFiles ( swaggerDocumentOne , options ) , swaggerUi . setup ( swaggerDocumentOne ) ) ;

app . use ( '/api-docs-two' , swaggerUi . serveFiles ( swaggerDocumentTwo , options ) , swaggerUi . setup ( swaggerDocumentTwo ) ) ;

app . use ( '/api-docs-dynamic' , function ( req , res , next ) {
  req . swaggerDoc = swaggerDocument ;
  next ( ) ;
} , swaggerUi . serveFiles ( ) , swaggerUi . setup ( ) ) ;

Swagger 문서 링크

Swagger UI 내에서 다운로드 할 Swagger 문서에 대한 링크를 렌더링하려면 Swagger Doc을 엔드 포인트로 제공하고 URL 옵션을 사용하여 다음을 가리 킵니다.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
    swaggerOptions : {
        url : "/api-docs/swagger.json" ,
    } ,
}
app . get ( "/api-docs/swagger.json" , ( req , res ) => res . json ( swaggerDocument ) ) ;
app . use ( '/api-docs' , swaggerUi . serveFiles ( null , options ) , swaggerUi . setup ( null , options ) ) ; 

요구 사항

• 노드 v0.10.32 이상
• 4 이상을 표현하십시오

테스트

• 팬텀을 설치하십시오
• npm install
• npm test