TIL 73 (Swagger)

 

What Is Swagger? 출처

 

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.

 

Swagger는 OpenAPI 사양에 따라 구축된 오픈 소스 도구 세트입니다. REST API의 설계, 구축, 문서화 및 사용을 지원합니다.

 

공식 페이지에서는 Swagger를 다음과 같이 설명하고 있습니다.

 

위키백과에서는 다음과 같이 표현합니다. 출처

 

스웨거(Swagger)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.

 

저는 이러한 Swagger를 API 문서를 작성을 자동화하기 위해 학습하고 개인프로젝트에서 반영해보았습니다.

 

아래의 코드처럼 Swagger를 사용하기 위해 2개 모듈을 dev로 설치해줍니다.

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

 

server에 swagger 폴더와 swagger.js 파일을 만들어주었습니다.

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

const options = {
  swaggerDefinition: {
    openapi: "3.0.0", // 오픈 api의 버전
    info: {
      version: "1.0.0",
      title: "theMenu", 
      description:
        "직장인들의 영원한 숙제, 몇 가지 질문으로 드시고 싶은 메뉴를 골라보세요. 사용자의 위치에 기반해서 식당을 추천해드립니다.",
    },
    servers: [
      {
        url: "http://localhost:4000",
      },
    ],
  },
  apis: ["./router/*.js", "./router/user/*.js", "./router/menu/*.js"],
}
const specs = swaggereJsdoc(options)

module.exports = { swaggerUi, specs }

그리고 app.js에 다음과 같이 연결해주었습니다.

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

const router = require('./router/index');
dotenv.config();
const app = express();
const port = 4000;

app.use(morgan('dev'));
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cookieParser());

app.use('/', router);

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

그리고 router 폴더의 index.js에 swagger 정보를 작성했습니다.

router.use('/user', userRoute);
/**
 * @swagger
 * tags:
 *   name: User
 *   description: 로그인, 로그아웃, 회원가입, 탈퇴, 사용자 정보 조회, 사용자 정보 수정
 */

router.use('/menu', menuRoute);
/**
 * @swagger
 * tags:
 *   name: Menu
 *   description: 선택된 메뉴, 내 메뉴 보기, 내 메뉴 저장
 */

이렇게 연결을 해주면 http://localhost:4000/api-docs 에 접속했을 때 다음과 같은 화면을 볼 수 있었습니다.

이제는 각 라우터 별로 정보를 정보를 작성해주었습니다. 먼저 로그인입니다.

학습하고 반영하면서 작성하고 있는데 아직은 미숙하지만, swagger의 장점을 경험할 수 있었습니다.

위의 사진은 controller는 완성되어 있는 상태에서 swagger 코드를 입력하고 로그인 정보를 넣었을 때 에러와 정상 처리에 대한 사진입니다. 전체적으로 캡쳐를 하다보니 사진이 조금 흐립니다.

 

parameters 옆에 try it out을 클릭하고 request body부분에 email과 password를 입력한 다음 excute를 눌렀을 때 response가 정상적으로 출력되는 것을 확인할 수 있었습니다.

 

나머지 부분도 작성하면서 알게되는 것이나 각 요청 별로 반영하는 것이나 추가적으로 작성하도록 하겠습니다.