사이드 프로젝트에서 swagger를 적용한 내용을 공유합니다.
postman 문서를 사용하는데에도 큰 불편함이 없었는데도 swagger를 적용하고 나니 너무 편합니다.
API 문서 작성에 불편함을 느끼고 있다면 강추드립니다.👍👍
swagger는 다양한 언어를 지원하며 이 글에서는 nodeJS를 기준으로 설명합니다.
예제는 github에서 확인하실 수 있습니다.
Swagger란
swagger는 REST API를 편리하게 문서화해주고 설계, 빌드, 조회하는 일을 지원해주는 프레임워크입니다.
간단하게 API 문서를 작성할 수 있으며 내용만 작성하면 아래 사진처럼 페이지를 자동으로 빌드해줍니다.
UI가 깔끔해서 문서가 한눈에 들어오고 postman처럼 API를 호출 해볼 수도 있습니다!
API를 선택하면 Parameters, Response 에 대한 설명을 확인할 수 있습니다.
Parameters옆 Try it out 버튼을 클릭하면 API가 실행됩니다.
swagger의 장점
개발, API 문서 작성, 테스트를 한번에
swagger를 적용하기 전에는 postman의 문서 작성 기능을 이용해서 API 문서를 작성했었습니다.
API 테스트와 문서 작성을 한번에 할 수 있는건 좋았지만 코드와 분리되어 있다보니 개발이 진행될수록 문서가 업데이트 되는 속도가 느려졌었습니다.
swagger를 이용하면 개발, API 문서 작성, 테스트를 한번에 할 수 있습니다!(뒷광고 아닙니다)
컬럼의 컴포넌트화
문서를 작성하다보면 반복되는 부분이 생기기 마련입니다,
복사 - 붙여넣기로 똑같은 부분을 작성하고, 나중에 수정이 되면 사용되는 부분을 모두 찾아 바꿔야 합니다.
swagger에서는 component를 정의할 수 있어 반복되는 코드를 줄일 수 있습니다.
다중 구조도 지원하므로 NoSQL에서 스키마에 맞춰 사용이 가능합니다.
// 컴포넌트 정의
/**
* @swagger
* components:
* schemas:
* Comment:
* properties:
* author:
* type: string
* description: 작성자 ID
* example: '63574b3b37ad67001411ba50'
* content:
* type: string
* description: 댓글 내용
*/
// 컴포넌트 사용
/**
* @swagger
* paths:
* /posts/comments/{id}:
* get:
* tags:
* - comments
* summary:
* description:
* parameters:
* responses:
* 200:
* description: successful operation
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/Comment'
*/
Response도 컴포넌트화가 가능합니다.
401(UnauthorizedError) 에러가 발생하는 경우에도 컴포넌트를 사용하면 됩니다.
// 컴포넌트 정의
/**
* @swagger
* components:
* securitySchemes:
* bearerAuth:
* type: http
* scheme: bearer
* bearerFormat: JWT
* responses:
* UnauthorizedError:
* description: Access token is missing or invalid
*/
// 사용 시
/**
* @swagger
* paths:
* /posts:
* description:
* requestBody:
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Post'
* responses:
* 201:
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/Post'
* 401:
* $ref: '#/components/responses/UnauthorizedError'
*/
Node.JS(express) 프로젝트에 Swagger 적용하기
세팅하는 방법은 간단합니다.
1. 모듈 Install
npm install swagger-cli swagger-ui-express yamljs
2. swagger.js 파일 생성
const options = {
swaggerDefinition: {
openapi: '3.0.3',
info: {
title: 'API Docs.',
version: '1.0.0',
description: 'API 문서입니다.',
},
servers: [
{
url: 'http://127.0.0.1:5000/api',
},
],
},
apis: ['**/*.js'],
};
export default options;3. express load 시 swagger API 적용
// Swagger
const specs = swaggerJSDoc(swaggerOption);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
서버를 실행하고 http://127.0.0.1:port/api-doc 로 접속해보면 세팅이 완료됩니다.
코드에서 @swagger로 정의한 내용을 swagger가 자동으로 인식하며 API 문서를 생성합니다.
DB(model)에 해당되는 코드에서 컴포넌트를 정의하고
/**
* @swagger
* components:
* schemas:
* Comment:
* properties:
* author:
* type: string
* description: 작성자 ID
* example: '63574b3b37ad67001411ba50'
* content:
* type: string
* description: 댓글 내용
*/컨트롤러(routes)에 API에 대한 정보를 입력해줍니다.
/**
* @swagger
* paths:
* /posts/comments:
* post:
* tags:
* - comments
* summary: 댓글 등록
* description: '신규 댓글을 등록한다.'
* requestBody:
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/Comment'
* responses:
* 201:
* description: successful operation
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/Comment'
*/서버를 다시 실행해보면
API가 추가된 것을 확인할 수 있습니다.
이제 개발을 진행하며 바로 문서를 작성할 수 있고 따로 주석을 달지 않아도 어떤 API인지 알 수 있습니다.
다양한 예제는 공식 Editor에서 확인할 수 있고 공식 문서가 잘되어 있으니 읽어보시는걸 추천드립니다.
👉 다음 글에서 이어집니다.
nodeJS(typescript)에 swagger 적용하기
참고 글
귀찮은 api 문서 swagger UI로 자동화 (nodejs)
Node.js (TS) 프로젝트에 swagger 적용하기 (Feat. 파일 분리)
'Node.js' 카테고리의 다른 글
| nodeJS(typescript)에 swagger 적용하기 (0) | 2022.11.04 |
|---|---|
| NodeJS 환경에서 부하테스트 진행하기(Artillery 이용) (1) | 2022.05.19 |
| Node.js란? Node.js 특징 정리(이벤트 기반, 논 블로킹 I/O 모델) (1) | 2021.11.19 |
| Node.js(express) 프로젝트 설계하기 (8) | 2021.08.31 |
| [Node.js] __dirname is not defined 에러 (0) | 2021.01.27 |