kalgooksoo / spring-boot-cms

spring-boot-cms

spring-boot-cms

태스크 목록 바로가기

목차

1. 프로젝트 정보
2. 구동 절차
3. 서비스 구성

프로젝트 정보

구동 절차

CmsApplication 실행

서비스 구성

• 계정
• 게시판

spring-boot-cms's Issues

API Docs 변경안

현재 API 명세는 OAS에 근거한 Swagger UI로 제공하고 있다.
하지만 프로덕션 코드에 API 문서에 들어갈 코드가 점점 더 많아지고 있다.
아래 예시 코드를 확인해보자

package com.kalgooksoo.cms.user.command;

import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

/**
 * 계정 수정 명령
 *
 * @param name                이름
 * @param emailId             이메일 ID
 * @param emailDomain         이메일 도메인
 * @param firstContactNumber  첫 번째 연락처 번호
 * @param middleContactNumber 두 번째 연락처 번호
 * @param lastContactNumber   마지막 연락처 번호
 */
@Schema(description = "계정 수정 명령")
public record UpdateUserCommand(
        @Parameter(description = "이름", required = true)
        @Schema(description = "이름", example = "홍길동")
        @NotBlank
        @Size(min = 2, max = 20)
        String name,

        @Parameter(description = "이메일 ID")
        @Schema(description = "이메일 ID", example = "testuser")
        String emailId,

        @Parameter(description = "이메일 도메인")
        @Schema(description = "이메일 도메인", example = "kalgooksoo.com")
        String emailDomain,

        @Parameter(description = "첫 번째 연락처 번호")
        @Schema(description = "첫 번째 연락처 번호", example = "010")
        String firstContactNumber,

        @Parameter(description = "두 번째 연락처 번호")
        @Schema(description = "두 번째 연락처 번호", example = "1234")
        String middleContactNumber,

        @Parameter(description = "마지막 연락처 번호")
        @Schema(description = "마지막 연락처 번호", example = "5678")
        String lastContactNumber
) {}

Swagger는 즉시 실행해볼 수 있는 아주 매력적인 툴이긴 하지만 어차피 쓸만큼 써봤고 책임을 분리하기 위해 Spring REST Docs를 써볼까 한다.

Spring REST Docs는 테스트 코드를 기반으로 API 문서를 빌드하는 라이러리라고 알고 있다. 한 번 도입해보자