Swagger UI 초기설정

Swagger UI란 ?

swagger를 정의하기에 앞서, 필요성에 대해 이야기 해볼게요.

 

 

API 제작이 끝난 후에, 프론트 분에게 완성된 API를 전달합니다.

 

여러분들은 어떻게 전달해주시나요?

github Wiki 나, md 파일, 엑셀, notion 등 많은 방법이 있습니다.

하지만, 모두 공통점은 수기로 작성해야 한다는 점이죠.

 

API를 공유할 때 문제점은 없었나요 ?

수기로 작성할 때에는 꼼꼼한 확인이 필요하죠.

특히 API는 정해진 규칙을 따르기 때문에 오탈자 하나도 큰 영향을 줄 수 있어요.

 

혹은, API를 수정을 할 때에도 API 명세서를 수정하지 않으면 문제가 발생합니다.

 

이러한 문제점을 해결할 수 있는 방법이 바로 Swagger입니다.

 

Swagger settings

1. node module 설치

npm i swagger-jsdoc swagger-ui-express --save-dev

swagger는 개발용 모듈이기 때문에 devDependencies에 추가해줘야겠죠

그래서 [--save-dev] 옵션을 붙여주었습니다.

 

2. option

지금부터는 Basic Structure를 설정해볼게요.

공식 문서에 더 자세히 나와있습니다. 

 

프로젝트 구조와 파일 형식은 다 다르겠지만, 저는 swagger라는 폴더에 swagger.js 파일을 만들었습니다.

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

const options = {
    swaggerDefinition: {
        info: {
            title: 'Test API',
            version: '1.0.0',
            description: 'Test API with express',
        },
        host: 'localhost:8080',
        basePath: '/'
    },
    apis: ['../routes/*.js', './swagger/*']
};

const specs = swaggereJsdoc(options);

module.exports = {
    swaggerUi,
    specs
};

모듈을 불러오고 옵션을 설정한 내용들 뿐입니다.

swaggerDefinition는 yaml 형식이나 json 형식을 받습니다.위는 json을 사용했죠 〰️ 

 

info 객체는 title, version, description 을 설정했습니다.

링크에 들어가시면 더 자세한 내용들을 확인할 수 있습니다 !

 

apis 는 내가 설정한 api들을 swagger가 찾을 수 있도록 표시해줍니다.

"../routes 폴더 아래 js 파일 내에 정의 하고 있으며,

./swagger 폴더 아래 swagger 설정을 정의하고 있다"를 명시해준거죠. 

 

3. app.js 라우팅 설정

먼저, Swagger.js 를 불러옵니다.

const { swaggerUi, specs } = require('./swagger/swagger');

그리곤, /api-docs 라는 path로 등록시켜줍니다.

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

이 부분은 모든 path를 정의하기 전 (express에서는 indexRouter 윗 부분) 에 정의하는 게 좋겠죠?

 

여기까지 했다면, 설정은 끝났습니다.

여기까지 실행을 해보면 /api-docs 에 아래와 같이 뜨는 것을 확인할 수 있습니다 !