이번 글은 Node.js (Express) 프로젝트에 Swagger를 세팅하는 방법에 대해서 작성하도록 하겠습니다.

Swagger를 많이 들어보기는 했지만 회사가 아무래도 정신없이 프로젝트가 진행되다보니 정말 중요한 API 문서화를 하지 않아서 아직까지도 사용을 못해봤었는데 최근에 소규모의 프로젝트를 진행하게 되면서 Swagger를 접하게 되었습니다. 🙌🏻 (드디어!!) 그래서 따로 Swagger에 대해서 공부하고서 적용하는 것이 좋을 것 같아서 작성하게 되었습니다.

1️⃣   프로젝트 초기세팅

1-1. 프로젝트 초기화

우선 swagger_project 라는 폴더 생성 후 npm init 로 Node.js 프로젝트를 초기화하고 프로젝트의 package.json 파일을 생성합니다.

mkdir swagger_project
cd swagger_project
npm init -y

위의 명령어가 정상적으로 실행되면 아래와 같이 생성된 package.json 파일의 내용이 나옵니다. 설정한 프로젝트 이름에 따라 다를 수 있습니다.

1-2. 필요한 패키지 설치

Swagger 문서화하는 방법은 크게 3가지 방법(Annotation / JSON / YAML)이 있는데, 그중 YAML 파일을 사용하여 작성하기 위해 yamljs 패키지를 설치합니다.

npm install express swagger-ui-express yamljs

2️⃣   Express 서버 설정

2-1. 기본 서버 설정 (index.js)

패키지 설치까지 완료되었으면 이제 프로젝트 루트 디렉토리에 index.js 파일을 생성한 후, 아래와 같이 기본 Express 서버를 설정합니다. 아래 설정한 Express 서버는 3000 번 포트로 실행되며, / 경로로 GET 요청 시 "Express Server!" 를 반환합니다.

const express = require("express");
const app = express();
const port = 3000;

app.get("/", (req, res) => {
  res.send("Express Server!");
});

app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

3️⃣   Swagger 설정

이제 본격적으로 Swagger 설정을 해보도록 하겠습니다. 🧐 저는 YAML 파일 하나에 모든 API 를 설정하는 방법이 아닌 서비스별로 YAML 파일을 따로 가져가는 방법으로 작성하도록 하겠습니다.

3-1. 프로젝트 구조 설정

우선 서비스별로 가져가기 위해 폴더 및 파일을 생성해보도록 하겠습니다. User 라는 서비스, Product 라는 서비스가 있다고 가정하여 생성하였으며, 원하는 서비스명으로 변경하셔도 괜찮습니다.

3-2. 서비스별 YAML 파일 작성

폴더 및 파일을 생성하여 프로젝트 구조를 위와 같이 설정하였으면 이제 서비스별 YAML 파일을 작성해보겠습니다. 아래 코드는 user.yaml 파일입니다. (product.yaml 도 비슷한 형식으로 product에 맞게 바꿔주면 됩니다.)

get:
  summary: 사용자 조회
  responses:
    "200":
      description: 사용자 목록을 조회하는 API
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

3-3. 공통 swagger.yaml 파일 작성

위에서 서비스별 YAML 파일을 작성하였으면 이제는 각 서비스의 YAML 파일을 통합하여 공통 문서를 작성하기 위한 공통 swagger.xml을 만들 차례입니다. 아래와 같이 swagger.xml을 생성합니다.

openapi: 3.0.0
info:
  title: Swagger - API Document
  description: Swagger를 사용한 API Document
  version: 1.0.0
paths:
  /users:
    $ref: "./routes/user/user.yaml"
  /products:
    $ref: "./routes/product/product.yaml"
components:
  schemas:
    User:
      $ref: "./routes/user/user.yaml#/components/schemas/User"
    Product:
      $ref: "./routes/product/product.yaml#/components/schemas/Product"

• info : 문서의 기본 정보

  • title : API 문서의 제목
  • description : API 문서에 대한 설명
  • version : API 문서의 버전

• paths : API 엔드포인트 정의 (HTTP 메서드 관련 정보 포함)

  • $ref : 서비스별 YAML 파일에서 정의된 paths 정보 참조

• components : API 문서에서 재사용되는 구성 요소

  • schemas : 데이터 모델 (API에서 사용하는 데이터 구조)
  • $ref : 서비스별 YAML 파일에서 정의된 스키마 참조

3-4. Swagger 문서 파일 통합

이제 작성된 Swagger 문서 파일을 통합해보도록 하겠습니다. 어떤 방법으로 통합할지 검색해봤는데 index.js 파일에서 직접 YAML 파일을 읽어서 합치는 방법이 나오던데, 당장은 단순 예시이기 때문에 서비스가 2개만 있다고 하지만 추후에는 얼마나 서비스가 늘어날지 모르는 상황에서 좋지 않은 방법인 것 같아서 Swagger의 문서 자동 통합 도구를 사용하는 방법으로 진행해보겠습니다!

1) swagger-cli 패키지 설치

npm install -g swagger-cli

2) Swagger YAML 파일 통합

swagger-cli 명령어를 통해 Swagger YAML 파일을 통합합니다. (간단하죠?)

swagger-cli bundle swagger.yaml --outfile combined_swagger.yaml --type yaml

• swagger.yaml(공통 파일명)과 관련된 모든 참조를 해결하여 combined_swagger.yaml(생성될 통합 파일명) 파일을 생성합니다.

3) Express 라우팅 설정 및 통합된 파일 적용

2번에서 swagger-cli 명령어를 통해 만들어진 combined_swagger.yaml 파일을 가지고 Express에 적용하고, 어떤 URI로 요청했을 경우 Swagger API 문서를 볼 것인지에 대해 라우팅 설정합니다. index.js 에 Swagger UI를 추가한 후 api-docs 라는 URI 요청 시 Swagger UI를 통해 API 문서를 볼 수 있도록 설정합니다.

const express = require("express");
const swaggerUI = require("swagger-ui-express");
const YAML = require("yamljs");
const path = require("path");

const app = express();
const port = 3000;

// swagger 연결
const swagger = YAML.load(path.join(__dirname, "./combined_swagger.yaml"));
app.use("/api-docs", swaggerUI.serve, swaggerUI.setup(swagger));

app.get("/", (req, res) => {
  res.send("Hello World!");
});

app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

Swagger를 세팅하다가 문득 왜 get이 아닌 use일까? 라는 생각이 들어서 찾아보게 되어서 정리하는 겸 혹시나 저처럼 궁금해하시는 분들에게 도움이 되셨으면 하는 바람으로 남겨놓겠습니다. 🙇🏻‍♀️

app.use() 를 사용하는 이유는?

• app.use() 란?
  • Express에서 미들웨어를 설정하는 데 사용되는 함수이다.
  • 지정된 경로에 도달하는 모든 요청 (GET, POST, PUT, DELETE) 처리 가능하다.
  • 요청 URL을 지정하지 않아도 사용할 수 있으며 해당 경우에는 URL에 상관없이 매번 실행된다.

✅ Swagger 는 단순히 정적인 파일을 제공하는 것이 아닌 API 문서화와 관련된 다양한 기능을 제공하는 미들웨어이며, GET POST PUT DELETE 등 모든 HTTP 메서드에 작동하기 때문에 app.use()를 사용합니다.

위와 같이 설정한 후 node index.js 명령어를 터미널에 실행하면 http://localhost:3000/api-docs 에 접속하여 Swagger UI를 통해 API 문서를 볼 수 있습니다.

지금까지 Node(Express) 프로젝트에 Swagger 세팅하는 방법에 대해서 알아봤습니다. 확실히 많이 쓰는 데에는 이유가 있다고 생각하고 이제야 알게 되어 조금 늦은 것 같지만 이번 포스팅을 통해 알게 되었으니 실무에 적용을 해봐야겠다는 생각을 했습니다. 다만 제가 사용한 서비스별로 YAML을 통합하는 방법의 아쉬운 점은 "서비스의 yaml을 바꿀 때마다 swagger-cli 명령어를 입력해야된다는 점" 이었고, 어떤 식으로 개선할 수 있을지에 대해서도 시간이 된다면 포스팅할 예정입니다. 긴 글 읽어주셔서 감사합니다. 😊

🧐 공부하게 된 계기

회사에서 R 이라는 언어를 사용하면 대용량 크기의 엑셀 파일에서 중복을 빠르게 제거할 수 있다고 공부해보라고 하셔서 찾아보았다. (물론 R 이 아니어도 데이터베이스를 이용한 방법도 있었지만 - 이 방법도 수석님께서 알려주셨다. R 을 기존에 알지 않았다면 이 방법이 훨씬 빠른 방법 같다. 나중에 이것도 올려야겠다.)

📝 Today I Learned

• R 을 이용하여 엑셀 파일 불러오기
• R 을 이용하여 중복 제거하기
• R 을 이용하여 나온 중복 제거한 결과를 엑셀 파일로 저장하기

📋 후기

크게 나누면 위의 세 가지 정도 되는 것 같다. 처음에는 배우지도 않은 (통계에 사용되는 언어라는 것만 알고 있던) R 이라는 언어를 사용하려니까 막막하긴 했지만, 러닝 커브가 낮다고 하길래 어떻게든 되겠지 해보자! 라는 생각으로 달려들었다. 강의를 들으면서 해보려고 했지만, 원하는 게 나오지 않아서 구글링 위주로 해봤다. 시간은 생각보다 걸렸지만 그래도 막상 해내니까 뿌듯하기도 하고 기분이 진짜 좋았다. 공부한 R 에 대해서는 조금 더 정리해서 글을 올릴 예정이다. ( 이번 주 안으로는 올릴 계획이지만... 계획대로 될 지는 모르겠다. 그래도 꼭 올릴 수 있도록 노력해야지...! )

벌써 첫 직장에 다닌지 6개월 정도 되었다. 실제 업무에 투입이 되어 직접 업무를 하게 된 건 아직 2개월 정도 되었지만, 그동안 많은 것을 배운 것 같다. 근데 언제부턴가 지금까지 배웠던, 그리고 배우고 있는 것들을 나중에 생각해낼 수 있을까 의문이 들기 시작하면서 어디에라도 기록을 해놓으면 나중에 처음 헤맸던 것처럼 헤매진 않지 않을까? 생각이 들어 블로그를 찾아보기 시작했다. 이렇게 개발자들이 본인의 기술이나 프로젝트를 회고, 공부할 목적으로 운영하는 블로그를 기술 블로그 (개발 블로그) *라고 하는 것 같다. 바쁜 직장 생활과 병행하여 블로그를 잘 운영할 수 있을지 모르겠지만, 그래도 이왕 시작한 거 열심히 해보기로 결심했다. *적어도 일주일에 하나의 글은 정성스럽게 쓸 것이다! 아자아자!

1. Velog
2. Tistory
3. Github 블로그
4. 미디엄(medium)
5. Notion

블로그를 시작하기에 앞서 위 블로그 플랫폼 5가지를 두고 고민을 했다. (Notion은 블로그 플랫폼은 아니지만 예쁘고 Notion으로 블로그처럼 운영하는 방법도 있길래 추가해보았다.) 5가지 플랫폼 각각의 장∙단점에 대해서 아주아주 간단히 정리해보았다.  (지나친 Velog 위주입니다)

1. Velog

Velog는 프론트엔드 개발자 벨로펄트(Velopert) 님이 만든 블로그 서비스다. html, 마크다운을 사용해서 글을 작성할 수 있다는 점이 다른 블로그들과 차별화된 점이다. 간단하게 장∙단점을 살펴보자.

장점

• 심플한 디자인 ✏︎ 저처럼 심플하고 깔끔한 거 좋아하시는 분들에게 velog 디자인은 딱 좋을 거예요!

• html, 마크다운 사용 ✏︎ 그냥 글만 쓰는 건 지루할 수도 있는데 마크다운 사용하고, html 사용도 하니까 글 쓰면서도 코딩하는 기분이라 좋았어요! (저는 아무래도 개발이 체질인가 봐요ㅎㅎ ☻)

• 개발자가 만든 개발자를 위한 블로그라서 사용하기 편함

단점

• 유저가 많지 않고 방문수가 나타나지 않음 ✏︎ 이 부분에 있어서 저는 크게 신경쓰지 않았지만 방문수로 자극을 받고 열심히 쓰는 동기부여가 되기도 하는 분들이 많으신데... velog에는 방문수도 없고 유저도 그렇게 많진 않아요ㅜㅜ 그래도! 요즘은 velog가 떠오르는 추세니까~ 사용하다 보면 언젠간 유저 수가 많아지지 않을까요?

• 수익 / 통계 / 구독 기능이 없음 ✏︎ 대다수의 사람들이 블로그를 통해 돈을 벌고자 하시는 분들이 많은데... 아쉽게도 velog는 아직 그런 수익 기능?이 없어요... 저는 단지 공부한 것과 배운 것들을 기록하기 위해서 운영하는 블로그라 크게 신경쓰지 않았지만, 블로그를 통해 수익을 내고 싶으신 분이라면 참고하시기 바래요!

2. Tistory

Tistory는 포털사이트 Daum에서 제공하는 블로그 서빗로 블로그 제공서비스 중에 자유도와 무한 트래픽, 무한 용량을 제공하는 블로그 플랫폼이다. 또한 우리나라에서 네이버 블로그 다음으로 유명한 블로그 플랫폼이다. _(구글링을 하다 보면 10에 56은 티스토리 글이다.)_~~

장점

• 제작 & 관리가 쉬움 ✏︎ 일반 블로그처럼 시작하기 쉽고, 네이버 블로그보다 자유도가 높다.

• 커스터마이징이 쉬움 ✏︎ 괜찮은 템플릿이 좀 있어서 디자인 하기도 편해요! ㅎㅎ

• 수익 / 통계 / 구독 기능이 있음 ✏︎ 블로그를 통해 돈을 벌고 싶으신 분들에게는 딱인 블로그 플랫폼이에요..!

단점

• 마크다운으로 사용하기 불편함 ✏︎ 블로그 글을 작성하면서도 개발하는 기분을 느끼고 싶었던 저로서는 이 부분이 큰 단점으로 와닿아서... 티스토리는 과감하게 포기했습니당... 글 쓰면서도 재미가 있었으면 좋겠다고 생각했거든요.

• 네이버 검색 노출 순위가 밀림 ✏︎ 우리나라에서 많이 이용하는 네이버에서의 검색 노출 순위가 밀려서 방문자 유입이 많지가 않아서 수익을 목적으로 하시는 분들이라면... 티스토리는 다시 생각해보셔야 할 것 같아요.

3. Github 블로그

Github 블로그는 Github 저장소에 저장된 html 파일과 같은 정적 웹 문서들을 Github에서 무료로 웹에서 볼 수 있도록 호스팅 서비스를 제공해주는 것이다. 사용자마다 고유의 정적 웹 사이트를 1개 가질 수 있으며 Repository를 이용해서 자신만의 블로그 사이트를 만들 수 있는 블로그 플랫폼이다.

장점

• Github과 연동할 수 있음 ✏︎ Github과 연동할 수 있어서 버전 관리도 가능해요.

• Jekyll이나 Hexo를 이용하여 테마 사용 가능 ✏︎ 다양한 테마들이 있어서 자신이 원하는대로 커스터마이징 할 수 있음 (단, 어느정도의 코딩 실력이 필요...)

단점

• Git에 대한 지식 + 코딩을 어느 정도 해야 함 ✏︎ 애초에 Github 저장소와 연동되어 있는 플랫폼이기 때문에 Git을 어느정도 다룰 수 있어야 하고, 코딩도 어느 정도 해야 해요ㅜㅜ (저도 전에 해봤는데 진입 장벽이 좀 높다고 하더라고요...!)

✅ 그래도 시간적 여유가 있는 개발자 분들이라면 한번쯤은 해보시는 걸 추천드려요. 요즘 취업할 때 블로그도 하나의 포트폴리오로 보기 때문에 코딩으로 구현한 블로그라면 조금 더 점수를 얻을 수 있지 않을까요..? (저도 나중에 시간적 여유가 된다면 도전해보려고요 !!)

4. 미디엄 (Medium)

Medium은 Nginx에 node.js (자바스크립트 서버언어)로 구축된 사이트다. 워드프레스와 달리 Medium은 전적으로 블로깅에 관한 기능만 갖추고, 글쓰기, 읽기, 관련글 보기에 관련한 기능을 매우 강화한 플랫폼이다.

장점

• 심플한 디자인 ✏︎ velog와는 재질이 다른 심플이지만 그래도 깔끔하고 심플한 것을 좋아하시는 분이라면 딱일 듯 해요! ㅎㅎ

• 검색도 잘 되고, 참고할 수 있는 글이 많음 ✏︎ 애초에 유저가 많아서 그런지 구글에 검색도 잘 되고, 글이 많아서 참고할 수 있는 글도 많고, 읽을 것들도 많아요. 블로그 글이 검색이 잘 됐으면 좋겠고, 참고할 수 있는 글이 많았으면 좋겠다 싶으면 미디엄이 딱이겠네요!

단점

• 미디엄만의 특유 스타일 ✏︎ 미디엄 글을 한 번이라도 읽어보셨다면 아시겠지만, 미디엄은 그 특유의 느낌이 있어요.. 저는 그 특유의 스타일이 접근하기도 어렵고 글을 잘 써야될 것 같고 부담스럽더라구요ㅠㅠ 그래서 깔끔하게 포기!

5. Notion

Notion은 많은 사람들이 아시다시피 노트, 일정, 업무, 데이터, 프로젝트 등을 효율적으로 생성하고 관리할 수 있게 도와주는 온라인 올인원 협업 도구이다.

장점

• 예쁜 디자인 ✏︎ 메모를 하든 글을 쓰든 뭘 하든 그냥 예쁘다. 심플하면서도 예쁜 느낌... 이 느낌 때문에 노션을 버릴 수 없다ㅜㅜ

단점

• 블로그, 개인 웹사이트로서 사용하기에는 조금 부족함 ✏︎ 노트 같은 느낌이 강해서 그런지 사이트로는 사용하기에 부족한 것 같아요..! 예뻐도 아쉽지만... 포기를 ㅠㅠ

최종선택은 !?

이렇게 찾아본 결과 제 선택은! 이미 예측하셨겠지만 Velog 였습니다. (지나치게 velog의 장∙단점이 많았죠...? 근데 어쩔 수 없었어요 그래서 velog를 선택했습니다~) 저는 제가 쓸 블로그 용도에 맞게 선택했으니, 여러분들도 여러분이 쓸 블로그의 용도에 맞게 선택하길 바랄게요!

첫 블로그 글이었는데도 이렇게 긴 글 읽어주셔서 감사합니다! 이제 슬슬 회사 생활이나 공부한 거에 대한 기록 같은 걸로 찾아올게요 ☻