Swagger
swagger
postman 밖에 안 써봤는데, 이번에 프로젝트를 통해서 Swagger라는 툴을 알게 되었다. 이번 글은 간단하게 node.js에서 Swagger를 사용하는 법에 대해 정리하고자 한다.
swagger
사용하기우선 관련 패키지를 설치해야 한다
npm i swagger-autogen swagger-ui-express
npm: swagger-autogen
npm: swagger-ui-express
// swagger/swagger.js
const swaggerAutogen = require('swagger-autogen')({ openapi: '3.0.0' });
const options = {
info: {
title: 'This is my API Document',
description: '게시글 관리 api 서버',
},
servers: [
{
url: 'http://localhost:3000',
},
],
schemes: ['http'],
};
const outputFile = './swagger/swagger-output.json';
const endpointsFiles = ['./components/post/postRoute.js', './components/user/userRoute.js'];
swaggerAutogen(outputFile, endpointsFiles, options);
url
: 사용할 url을 입력한다.
outputFile
: swaggerAutogen을 통해 만들어질 api 문서(json)의 위치 및 이름을 지정한다.
endpointsFiles
: [ .. ] 배열 안에 자동으로 만들어질 Route파일을 연결한다. 파일 내부의
app.post('/user', .. )
를 찾아서 만들어질 api 문서(outputFile
)에 반영한다.
node ./swagger/swagger.js
만든 swagger.js 를 실행시키면, outputFile로 지정한 swagger-output.json 이 만들어진다.
이 코드는 자동으로 생성되니, 주의깊게 보지 않아도 된다.
// swagger-output.json
{
"openapi": "3.0.0",
"info": {
"title": "게시글 관리 api 서버",
"description": " 온보딩 2차 과제",
"version": "1.0.0"
},
"servers": [
{
"url": "http://localhost:3000"
}
],
"paths": {
"/post": {
"get": {
"description": "모든 게시글 불러오기",
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "게시글 목록"
}
}
},
"post": {
"description": "게시글 등록하기",
"parameters": [],
"responses": {
"200": {
"description": "message: 게시글 등록 완료"
},
"500": {
"description": "message: 비밀번호 규정을 지켜주세요"
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"example": "오날 날씨 정말 좋지 않나요??"
},
"content": {
"example": "이런 날씨엔 밖에 나가서 아아 한잔 해야하는데!!☕☕"
},
"password": {
"example": "12345aa"
},
"userId": {
"example": "1"
}
}
}
}
}
}
}
}
}
}
{ .. } 가 너무 많아져서 지저분하지만, 간단하게 이해하면
{
"openapi": "3.0.0",
"info":{..},
"server":{..},
"paths" : {
"/urlName":{
"method":{..},
"method":{..},
}
}
}
이런 구조이다.
여기서 method
를 좀 더 자세하게 살펴보면
"method":{
"description": "해당 url+method의 기능 설명",
"parameters": [],
"responses": {
"200": {
"description": "httpcode 200일때 설명"
},
"500": {
"description": "httpcode 500일때 설명"
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"example": "req.body.title 내용"
},
"content": {
"example": "req.body.content 내용"
},
...
}
자세히 살펴보면 직관적인 내용이다.
이제 작성된 json을 기준으로 api 문서 웹 페이지를 확인해 보자
app.js 에 관련 라우터를 추가한다.
// app.js
const swaggerFile = require('./swagger/swagger-output');
const swaggerUi = require('swagger-ui-express')
...
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerFile, {explorer:true}))
...
로컬에서 진행했기 때문에,http://localhost:3000/api-docs
에서 확인 가능하다.
이렇게 swagger 설정을 해 보았다.
추후 api 서버를 배포하고 test용 링크를 http://server/api-docs
로 README.md에 작성하는 등 다양하게 활용이 가능하다.