항해 99 TIL-24 Swagger (in Node.js)

스웨거란

• 백엔드 코드를 백엔드 개발자들만 가지고 있어, 프론트 개발자들이 각 API의 결과값이 어떤지를 직접 확인할 수가 없었음
• Swagger는 백엔드가 작성한 각 API들을 시각화하고 작동까지 할 수 있게 해줌으로써 프론트엔드 개발자들이 더 쉽게 API 명세서를 이해할 수 있도록 도움. ( + 백엔드 개발자들에게도 본인이 직접 작성하지 않은 API를 더 쉽게 이해할 수 있게 도움.)

<작성 방법>

1. yaml파일(혹은 json파일) 작성
   • Swagger (https://swagger.io) 에서 가입하고 작성
   • vsCode에서 직접 작성하는 방법도 있지만, 이 경우에는 어디에서 어떤 부분이 틀렸는지 알 수가 없다. (swagger.io에서 작성시에는 알 수 있다.)
   • (Swagger.io에서의 작성 화면)

(Swagger.io에서 작성시 문법이 틀린 내용을 알려주는 화면)

<코드 작성 문법 몇가지 예시>

• 연동할 서버 입력 예시

결과 화면 : 이처럼 입력한 url 목록이 나오고 그 중에 선택한 서버로 연결되게 된다.

GET API 예시

POST API 예시

Scheme 작성 예시

2. 작성한 Swagger를 .yaml 파일로 추출하기

우측 상단에 “Export”를 눌러 “Server Stub” - “nodejs-server”를 누르면 압축 파일이 하나 다운로드 된다.

• 참고 화면

• 압축 해제 후 api 폴더를 복사하여 원래 작업하던 프로젝트가 있는 폴더에 붙여넣어 준다. 우리의 목적은 “.yaml”파일 뿐이다.
• 참고화면(다운로드한 압축파일을 압축해제한 화면)

참고화면(api 폴더 내부의 모습. .yaml 파일만 있으면 됩니다.)

참고화면(이렇게 작업중인 프로젝트에 잘 들어가면 된다.)

3. 작성한 스웨거 파일과 진행중인 프로젝트를 연결시키기

• swagger-ui-express 모듈을 사용하면 “.yaml”파일 읽어 아래 참고화면과 같은 비쥬얼로 꾸며준다.
• 참고화면(swagger-ui-express가 “.yaml”파일을 읽어 화면을 만들어준 모습)

• swagger-ui-express 모듈이 “.yaml” 파일을 인식하려면 “.yaml”파일을 json형식으로 변환해줘야 하고, 이를 위해 “yamljs” 모듈을 사용한다.

Load Swagger from yaml file

• To load your swagger specification yaml file you need to use a module able to convert yaml to json; for instance yamljs. <https://github.com/scottie1984/swagger-ui-express 내용 중>

npm install --save yamljs

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./swagger.yaml');

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

- 추가로 “/app-docs” url로 Swagger가 작동하게 해준다.

 

4. 여기까지 하면 완성이다. 전체적인 흐름을 정리해보면 이런 순서가 된다.