728x90
반응형
우연히 어떤 글을 보고 swagger로 api docs를 작성할 수 있다는 것을 알게 되었다. 혼자 프로젝트 진행할 때 api가 너무 많아서 노션으로 일일이 작성해서 봤었는데 이 방법이 더 편리할 것 같아 한번 해보고 글로 작성할려고 한다.
1. swagger 설치
이전에 있던 express 프로젝트를 가져와 아래의 모듈을 설치한다.
npm install swagger-jsdoc swagger-ui-express --save-dev
- swagger-ui-express : API 문서 UI 렌더링을 위한 패키지
- swagger-jsdoc: Swagger 태그 주석을 추가해 API 문서화를 위한 패키지
- 개발할 때 보기 위함이기에 —save-dev옵션을 준다.
2. swagger 파일 설정
1) swagger.js 파일 만들기
// swagger.js
const swaggerUi = require("swagger-ui-express")
const swaggereJsdoc = require("swagger-jsdoc")
const options = {
swaggerDefinition: {
openapi: "3.0.0",
info: {
version: "1.0.0",
title: "유희왕의 포트폴리오",
description:
"Next.js를 기반으로 한 포트폴리오로 notion api 사용하여 db 기능 사용 ",
},
servers: [
{
url: "<http://localhost:3001>", // 요청 URL
},
],
},
apis: ["./*.js"], //Swagger 파일 연동
}
const specs = swaggereJsdoc(options)
module.exports = { swaggerUi, specs }
반응형
swaggerDefinition 구성 요소
- openapi : 사용하는 Open API의 버전, 공식문서에 버전이 나와있다. 편한 버전을 선택하여 이용하면 된다.
- info: API에 필요한 정보
- title: API 제목
- version: API 버전
- description: API 상세정보
- servers: API에 대한 기본 URL, 배열로 여러 URL 정의 가능 (host, basePath 이용하는 방법도 있음)
- components: 모든 API에 사용할 공통 컴포넌트
- schemes: 가능한 통신 방식 ex) ["http"], ["https"], ["http", "https"]
- defomotopms: DB 모델 정의
- apis: 어노테이션을 포함한 파일위치, 위치를 잘못 설정하면 해당 파일에 대한 설명이 안보인다.
해당 파일은 편한 곳에 추가하여 옵션을 정의하면 된다.
2) app.js에 swagger.js 정의하기
//app.js
const { swaggerUi, specs } = require("./swagger")
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs))
아까 작성한 swagger파일을 가져와 app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs)) 부분에서 UI와 옵션을 Express Router 환경에 연결한다.
3) api-docs 경로 확인하기
/api-docs 경로로 접속하면 위와 같은 페이지가 보인다.
3. API 문서화하기
/**
* @swagger
* tags:
* name: Slack
* description: slack에 메시지 보내기
*/
파일을 하나 따로 만들어 위와 같은 주석을 작성해준다. @swagger 태그를 적용하면 해당 주석은 Swagger정보를 작성할 수 있다.
문서 자세히 보기
const router = require("express").Router()
/**
* @swagger
* paths:
* /slack:
* get:
* summary: "slack으로 메시지 보내기"
* description: "Post방식으로 메시지 보내기 요청"
* tags: [Slack]
* responses:
* "200":
* description: 메시지 보내기 성공
* content:
* application/json:
* schema:
* type: object
* properties:
* ok:
* type: boolean
* users:
* type: object
* example:
* [
* { "name": "유희왕", "phone": "01010101012", "email": "dbgmldhkd@gmail.com", "text": "멋져부러" },
* { "name": "유희왕언니", "phone": "01010101012", "email": "dbgmldhkd@gmail.com", "text": "집들어와라" },
* { "name": "유희왕마미", "phone": "01010101012", "email": "dbgmldhkd@gmail.com", "text": "딸 오디니" },
* ]
*/
module.exports = router
해당 api에 대한 정보를 자세히 적으면 펼쳐서 내용을 확인할 수 있다.
👇🏻 참고
728x90
반응형
