오늘 뭐했냐/개발에 대한 주저리

23.09.03 스웨거(Swagger)

스스로에게 2023. 9. 9. 20:58

스웨거

API 문서를 설계, 문서화, 테스트 및 시각화하기 위한 오픈 소스 프레임워크 및 도구 세트이다. 주로 RESTful 웹 서비스 및 HTTP API에 대한 문서화에 사용된다. 이를 활용하면 개발자 및 API 사용자가 API를 더 쉽게 이해하고 사용할 수 있으며, 개발자 간의 협업을 간편하게 할 수 있습니다.

 

주요 구성 요소와 기능

  1. Swagger 스펙 또는 OpenAPI 스펙: Swagger는 API 설계 및 문서화에 사용되는 스펙을 정의한다. 이 스펙은 API 엔드포인트, 요청 및 응답 형식, 파라미터, 응답 코드 및 기타 API 정보를 정의하는 JSON 또는 YAML 형식의 문서이다. 여기에 API의 형태와 동작을 기술한다.
  2. Swagger UI: Swagger UI는 Swagger 스펙을 시각적으로 표시하고 상호작용할 수 있는 사용자 인터페이스를 제공한다. Swagger UI를 사용하면 개발자는 API 문서를 브라우징하고 API 엔드포인트를 테스트할 수 있다. Swagger UI는 웹 브라우저에서 실행되며 API 엔드포인트의 설명, 요청 및 응답 예제를 제공한다.
  3. wagger Codegen: Swagger Codegen은 Swagger 스펙을 기반으로 클라이언트 및 서버 코드를 자동으로 생성하는 도구이다.
  4. Swagger Editor: Swagger Editor는 Swagger 스펙을 작성 및 편집할 수 있는 온라인 편집기이다. Swagger 스펙을 작성할 때 문법 오류를 감지하고 스펙을 검증하여 문제를 미리 방지할 수 있다.

 

작동 방식

  1. 설정 및 스펙 작성:
    • Swagger를 사용하려면 먼저 Swagger 문서를 작성해야 한다. 여기에 API 엔드포인트, 요청 및 응답 형식, 서버 정보 및 API 버전과 같은 API에 대한 기본 정보를 포함한다.
  2. 스펙 생성:
    • Swagger 문서를 작성한 후, 이 정보를 바탕으로 Swagger 스펙 또는 OpenAPI 스펙을 자동으로 생성한다. 스펙은 API를 정의하고 문서화한 것으로, JSON 또는 YAML 형식의 파일로 나타낼 수 있다.
  3. UI 통합:
    • Swagger UI를 사용하여 생성된 Swagger 스펙을 시각적으로 표시하고 API를 테스트할 수 있는 사용자 인터페이스를 생성한다. 이 UI는 웹 브라우저에서 실행되며 API 문서를 브라우징하고 테스트하는 데 사용된다.
  4. 애플리케이션 통합:
    • Express.js 또는 다른 웹 프레임워크를 사용하여 Swagger UI와 Swagger 스펙을 서버에 통합한다. Express.js 미들웨어를 사용하여 Swagger UI를 서버로 노출하고, Swagger 스펙을 API 경로와 연결한다.
  5. API 문서 노출 및 테스트:
    • 서버를 실행하고 Swagger UI에 액세스 하면 API 문서가 표시되는데, 이 문서를 사용하여 API 엔드포인트를 검색하고 각 엔드포인트에 대한 정보 및 테스트 기능을 활용할 수 있다.
  6. 관리 및 업데이트:
    • Swagger 스펙은 API 변경 사항이 있을 때 업데이트해야 한다. API에 새 엔드포인트를 추가하거나 변경된 엔드포인트 정보를 스펙에 반영하여 문서를 최신 상태로 유지해야 한다.

 

장점

  1. 문서화와 테스트: Swagger를 사용하면 API를 쉽게 문서화하고 테스트할 수 있다.
  2. 자동화된 문서 생성: Swagger는 API 코드의 주석을 기반으로 API 문서를 자동으로 생성한다. 
  3. 시각화 및 테스트: Swagger UI는 API를 시각적으로 표시하고 테스트할 수 있는 사용자 친화적인 환경을 제공한다.
  4. 툴 통합: Swagger는 다양한 도구와 플랫폼에서 사용할 수 있으며, 다양한 개발 언어 및 프레임워크와 통합된다.

 

단점

  1. 추가 작업 필요: API 주석을 작성해야 하므로 초기 구성에 시간과 노력이 필요하다. 또한 Swagger UI를 사용자 정의할 수 있지만 이때 추가 구성이 필요할 수 있습니다.
  2. 비교적 큰 파일 크기: Swagger UI를 포함한 Swagger 관련 파일은 상대적으로 큰 파일 크기를 가질 수 있으므로 대용량 프로젝트에서 관리하기에 어려울 수 있다.
  3. 보안 주의: Swagger 문서에는 API 엔드포인트 및 요청 형식에 대한 정보가 포함되므로 보안 주의가 필요하다.

 

// swagger.js
const swaggerUi = require("swagger-ui-express")
const swaggereJsdoc = require("swagger-jsdoc")
const path = require('path');


const options = {
    swaggerDefinition: {
        openapi: "3.0.0",
        info: {
            version: "1.0.0",
            title: "MemoryMingle",
            description:
                "친구, 지인들과 추억을 공유하는 서비스",
        },
        servers: [
            {
                url: "http://localhost:3000", // 요청 URL
            },
        ],
    },
    apis: [path.resolve(__dirname, '../src/routes/**/*.js')],
}
const specs = swaggereJsdoc(options)

module.exports = { swaggerUi, specs }
// signup.route.js
/**
 * @swagger
 * /signup:
 *  post:
 *    summary: 회원가입
 *    description: 사용자를 시스템에 등록합니다.
 *    tags: [Authentication]
 *    requestBody:
 *      description: 로그인 ID, 패스워드, 패스워드 확인 필드를 가진 객체
 *      required: true
 *      content:
 *        application/json:
 *          schema:
 *            type: object
 *            properties:
 *              loginId:
 *                type: string
 *                description: 로그인 ID
 *              password:
 *                type: string
 *                description: 패스워드
 *              confirm:
 *                type: string
 *                description: 패스워드 확인
 *    responses:
 *      '201':
 *        description: 회원가입이 완료되었습니다.
 *        headers:
 *          Set-Cookie:
 *            description: 쿠키에 저장되는 JWT 액세스 토큰과 리프레시 토큰
 *            schema:
 *              type: string
 *              example: 'MM=Bearer example_token; refreshToken=example_refresh_token'
 *        content:
 *          application/json:
 *            schema:
 *              type: object
 *              properties:
 *                userId:
 *                  type: integer
 *                  description: 생성된 사용자의 고유 ID
 *                message:
 *                  type: string
 *                  description: 결과 메시지
 *      '400':
 *        description: 잘못된 요청입니다. 이 에러는 유효성 검사에 실패했을 때에 따라 다른 메시지로 응답할 수 있습니다.
 */
router.post("/", asyncHandler(signupController.signup));
// app.js

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

app.use('/docs', swaggerUi.serve, swaggerUi.setup(specs));

 

실행시켰을 때 이렇게 나온다. 미들웨어로 엔드포인트가 만들어지고 주석에 각 부분이 자동으로 UI를 만들어 시각화해준다. 당연히 자동 줄맞춤도 안 되고 처음 작성하다 보니까 각 줄별로 무슨 역할을 하는지 하는지 이해하기 힘들었다. 구조가 어렵진 않아서 계속 사용하면 외워질 테지만 API별로 그에 맞게 작성을 해야 하니까 손이 많이 가긴 한다. 하지만 확실히 보기에 좋았다. 기존에는 노션에 표를 이용해서 API명세를 작성했는데 비교했을 때 확실히 더 좋았다. 

저작자표시 (새창열림)