API 문서의 부재
에라 귀찮은거 뭐하러 만들어 그냥 하면 되지! 했던 나.. 대체 왜 그랬니..?
프로젝트를 진행하던 도중 중대한(?) 문제가 발생했다
HTTP 상태 코드를 사용하는게 귀찮아서 res.send로 다 때려버렸는데
에러로 들어가야 할 값도 200으로 잡혀서 클라이언트쪽에서 에러를 캐치하질 못했다
morgan으로 확인해보니 res.status를 지정해주지 않아서 200이 디폴트로 잡힘
그랬더니 클라이언트 axios catch로 에러메세지가 들어가지 않고 then으로 에러가 들어가네? 엌ㅋㅋㅋㅋ
이참에 상태 코드도 지정해줄 겸 API도 문서화 시켜볼려고 이것 저것 찾다가 발견한게 Swagger다
그래서 Swagger 라는게 뭔데?
처음 개발하거나 유지보수할때 API 서버가 어떤 데이터를 주고 받는지에 대한 문서작업이 필요한데
이런 문서작업은 시간이 많이들뿐더러 API가 수정될 때마다 문서도 같이 수정해줘야한다
스웨거는 Open Api Specification(OAS)를 위한 프레임워크로
API들이 가지고 있는 스펙(Spec)을 명세, 관리할 수 있는 프로젝트 이며,
API가 수정되더라도 문서가 자동으로 갱신되는 장점이 있다
검색해보니 뭐.. 그렇다고 한다
Swagger 설치
npm install swagger-jsdoc swagger-ui-express --save-dev- swagger-jsdoc : jsdoc주석으로 Swagger API 문서를 표현하기 위해 사용
- swagger-ui-express: swagger-ui와 express를 연결하기 위해 사용
- dev: 개발단계에서만 사용하기 위해 설정
swagger.js
const swaggerUi = require("swagger-ui-express");
const swaggereJsdoc = require("swagger-jsdoc");
const options = {
swaggerDefinition: {
openapi: "3.0.0",
info: {
title: "VitaBidding",
//타이틀 이름
version: "1.0.0",
description: "VitaBidding API with Express",
//API 설명
},
servers: [
{
url: "https://localhost:8080",
//스웨거를 실행할 주소
},
],
components: {
securitySchemes: {
cookieAuth: {
type: "apiKey",
in: "header",
name: "session",
//토큰쓸때 쓰는 놈인가? 얜 주워와서 뭐하는 놈인지 모름
},
},
},
security: [
{
cookieAuth: [],
//얘도 모름
},
],
},
apis: ["./routes/*.js", "./models/*.js"],
//models: 시퀄라이즈
//routes: 라우터
};
const specs = swaggereJsdoc(options);
module.exports = { swaggerUi, specs };루트 디렉토리에 swagger.js 파일을 만들고 환경설정을 해줬다
index.js
...
const { swaggerUi, specs } = require("./swagger"); //스웨거 환경설정 연결
...
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs)); //스웨거 개같이 사용!
...
그런다음 루트디렉토리 index.js에서 스웨거 환경설정과 연결해줬다
routes/index.js
...
/**
* @swagger
* tags:
* name: User
* description: User management
*/
// 회원 CRUD API
router.use("/auth", userRouter.userPassport);
/**
* @swagger
* /auth/login:
* post:
* tags: [User]
* summary: 회원가입 & 로그인
* parameters:
* - in: passport
* type: string
* required: true
* name: Email
* description: 패스포트 모듈을 활용해서 소셜 로그인 구현 (Swagger API TEST 불가능)
* - in: passport
* type: string
* required: true
* name: Password
* description: 데이터베이스에 회원정보가 존재하지 않으면 자동으로 회원가입 후 로그인
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* email:
* type: string
* example: PassPort Modul Login SNS Email
* password:
* type: string
* example: PassPort Modul Login SNS Password
* responses:
* "200":
* description: USER_LOGIN_SUCCESS, 로그인 성공
* headers:
* session-cookie:
* schema:
* type: object
* description: Session Key
* content:
* application/json:
* schema:
* type: object
* properties:
* session-cookie:
* type: object
* example: {"cookie":{"originalMaxAge":86400000,"expires":"2023-02-16T07:31:14.877Z","secure":false,"httpOnly":true,"path":"/"},"passport":{"user":"안알랴줌"}}
* "403":
* description: 로그인 검사 미들웨어; 세션이 존재한 상태에서 접근
* content:
* application/json:
* schema:
* type: object
* properties:
* USER_LOGIN_SEARCH_MIDDLEWARES:
* type: object
* example: {isSuccess: false,code: 2000,message: "로그인이 필요합니다."}
*/
...연결해줬으니 뭐다? 개같이 문서 제작이다! 끼요옷!
스웨거는 희얀하게도 저렇게 주석처리를 해줘야 동작한다
근데 /* */ 주석은 무슨 스타일인걸까..?
Swagger API 접속 주소는 https://localhost:8080/api-docs 이녀석이다
왜? 위에서 이렇게 쓴다고 설정을 다 해줬으니까
그런다음 서버를 돌려서 확인해보면
대망의 결과
한시간 가량 찾아보고 적용해봤는데 꽤 괜찮게 나온다
사실 이 코드 저 코드 람쥐 마냥 주워담아서 구현해본거라 이렇게 하는게 맞는지....는 모르겠다 깔깔깔
기본지식이 1도 없다 이겁니다 ㅖ!?
보니까 만든 API 테스트도 스웨거에서 가능하다는데
소셜 로그인을 passport로 구현해서 그런지 안된다..라기보단 어떻게 해야되는지도 모르겠다
그냥 다른 API들 테스트 해보고 되면 오오옼! 뭐고 이거 개쩐당! 해야될듯
댓글