Swagger - swagger-ui-express, jsdoc

www.npmjs.com/package/swagger-ui-express

swagger-ui-express

yarn add swagger-ui-express swagger-jsdoc@6.0.0
yarn add @types/swagger-ui-express @types/swagger-jsdoc@6.0.0 -D 

 

스웨거 허브는 온라인 상에서 swagger를 작성할 수 있지만, 엔드 포인트를 시험해가면서 웹과 서버 코드를 왔다갔다 하는 인지적 비용 때문에 서버 내에 넣어서 swagger-ui를 사용하는 편이 더 많은 편이다. (그렇다고 없는 건 스웨거 허브를 안 쓴다는 건 아니다! 둘다 많이 쓴다!)

 

typescript-node-starter 보일러플레이트를 살펴보니 다음과 같은 꼴로 스웨거를 사용하고 있는 것을 확인할 수 있습니다.

express에서는 swagger-ui-express와 swagger-jsdoc을 사용하는 편입니다.

swagger-jsdoc이 7버전이 최신 버전으로 받아지는데 문제가 잘 생깁니다. 6버전을 이용하도록합시다!

 

기본적인 세팅

import swaggerUi from 'swagger-ui-express';
import swaggerJSDoc from 'swagger-jsdoc';

... 중략

private initializeSwagger() {
  const options = {
    swaggerDefinition: {
      openapi: '3.0.0',
      info: {
        title: 'Put Your API Name',
        version: '1.0.0',
        description: 'Example docs',
      },
      servers: [
        {
          url: `http://localhost:${this.port}`,
        },
      ],
    },
    apis: ['swagger.yaml'],
  };
   const specs = swaggerJSDoc(options);
  this.app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs, { explorer: true }));
}

 

swagger.yaml은 다음과 같이 작성하면 됩니다. 스웨거 허브에서 작성하단 야믈파일과 비슷합니다.

tags:
- name: users
  description: users API

paths:
# [GET] users
  /users:
    get:
      tags:
      - users
      summary: Find All Users
      responses:
        200:
          description: 'OK'
        500:
          description: 'Server Error'

schemes:
 - https
 - http

 

결과적으론 지정한 경로에 들어가면 swagger 파일을 볼 수 있습니다. 

 

 

 

 yaml 언제 이걸 다 작성하나, jsdoc으로 서버 코드에 곧바로 Swgger를 작성하고 싶어!

... 작성중

 

 

 

 

잘 정리해둔 문서)

공식문서보세요. 훨씬 잘 되어 있긴합니다. 

joooohee.tistory.com/10