이번에 팀프로젝트를 진행하면서 api명세를 위해서 swagger를 사용하기로 정했습니다.
1차 팀프로젝트때는 노션을 사용해서 명세를 했고 이번에는 새로운 툴을 사용해보고싶기도하고 더 간편하다고하여 swagger를 사용하게 되었습니다.
swagger 초기 설정
- 먼저 필요한 패키지를 설치합니다.
npm install swagger-jsdoc swagger-ui-express --save-dev- swagger-jsdoc : jsdoc주석으로 Swagger API 문서를 표현하기 위해 사용
- swagger-ui-express: swagger-ui와 express를 연결하기 위해 사용
- --save-dev: swagger는 개발용 모듈이기 때문에 devDependencies에 추가해줘야 합니다.
- swagger 설정 파일을 작성하고 swagger-jsdoc를 사용하여 API 명세를 생성합니다. 주로 swaggerDef 객체에 기본적인 정보를 정의하고 각 API 엔드포인트에 대한 정보를 추가합니다.
// swaggerDef.js
const swaggerJSDoc = require('swagger-jsdoc');
const options = {
openapi: '3.0.0',
info: {
title: 'Express API with Swagger',
version: '1.0.0',
description: 'API documentation with Swagger',
},
servers: [
{
url: 'http://localhost:3000', // 서버 주소
description: 'Development server',
},
],
apis: ['./routes/*.js'], // 라우트 파일들의 경로
};
const swaggerSpec = swaggerJSDoc(options);
module.exports = swaggerSpec;
"openapi: '3.0.0'는 OpenAPI Specification의 버전을 명시하는 부분입니다. Swagger는 OpenAPI Specification을 따르는데, OpenAPI Specification은 API에 대한 표준 명세를 정의하는 스펙입니다. 버전 3.0.0은 OpenAPI Specification의 세 번째 메이저 버전을 나타냅니다.
OpenAPI Specification은 API의 설계, 문서화, 테스트, 코드 생성 등을 위한 표준을 제공합니다. API의 구조, 엔드포인트, 파라미터, 응답 형식, 보안 정책 등을 명세화하여 클라이언트 및 서버 간의 상호 운용성을 향상시킵니다.
Swagger를 통해 작성하는 Swagger 명세는 내부적으로 OpenAPI Specification을 따르며, openapi 필드를 사용하여 사용하는 OpenAPI Specification의 버전을 명시합니다. 현재 가장 최신의 메이저 버전은 3.0.0이며, 이 버전을 명시함으로써 해당 명세를 따르는 도구 및 라이브러리가 이해하고 해석할 수 있습니다.
간단히 말해, openapi: '3.0.0'를 명시함으로써 명세화된 API가 OpenAPI Specification 3.0.0을 따른다는 것을 명시하는 것입니다."
info는 저희가 사용할 swagger에 대한 설명을 나타냅니다.
servers는 저희가 만들고있는 서버에 대한 정보를 나타냅니다.
apis는 api명세가 있는 라우트 파일들의 경로를 나타냅니다. swagger설정이 있는 경로도 표시할 수 있습니다.- Express 애플리케이션에서 Swagger 미들웨어를 추가하고 Swagger UI를 라우팅합니다.
// app.js 또는 서버 시작 파일
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swaggerDef'); // 앞서 작성한 Swagger 설정 파일
const app = express();
// ... 여러 가지 미들웨어와 라우트 설정 ...
// Swagger UI를 /api-docs 경로에 라우팅
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
// 서버 시작
const port = 3000;
app.listen(port, () => {
console.log(`서버가 http://localhost:${port} 에서 실행 중`);
});
여기까지 하면 swagger의 초기 설정이 끝납니다.
swagger 사용법
태그 설정
저는 라우트 파일에 태그를 설정했습니다.
/**
* @swagger
* tags:
* name: Waitmate
* description: 웨이트메이트 관련 API
*/name에 이름을 적고 description에 태그 설명을 적으면 됩니다.
아래 사진에서 파란 줄로 표시한 것들이 태그입니다.
api 명세
/**
* @swagger
* /waitmate:
* post:
* summary: 웨이트메이트(글) 등록
* tags: [Waitmate]
* responses:
* '200':
* description: Successful response
* content:
* application/json:
* example:
* message: 'Hello, Swagger!'
*/
router.post('/register', (req, res) => {
res.json({ message: 'Hello, Swagger!' });
});어떤 것들인지 설명을 해보자면
- /Waitmate: api의 경로
- post: http 요청 메소드
- summary: api에 대한 설명
- tags: [Waitmate]: 어떤 태그에 속하는 api인지(여기서는 Waitmate태그에 속함)
- responses: 응답결과
입니다.
위 코드의 결과입니다.
하나씩 변경해보시면서 익히면 금방 사용할 수 있습니다.
참고:
Node.js Swagger API 문서화
협업을 위한 swagger 설정하기 (feat node.js)
