0songha0

Springboot swagger 사용법 / 백엔드 API 문서 자동 생성 및 설정

스프링부트 스웨거 사용법

Gradle 의존성 추가

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

스웨거 사용을 위해서 build.gradle 파일에 Springdoc OpenAPI 라이브러리 의존성을 추가합니다.

Swagger UI 접속

http://localhost:8080/swagger-ui/index.html
또는
http://localhost:8080/swagger-ui.html
서버를 실행하면 Springdoc OpenAPI가 API 명세를 자동 생성하고,
Swagger UI가 시각화하여 API 문서를 제공합니다.

API 실행 테스트

API URL 클릭 > 펼쳐진 Parameters 우측 Try it out 클릭 > 파라미터 선택 및 입력 > Execute

스웨거 API 문서 작성 방법

컨트롤러 작성 예시

@Tag(name = "관리자", description = "관리자 전용 회원 관리 API (권한 필요)") // API 제목
@RestController
@RequestMapping("/api/v1/admin/members") // 공통 URL 매핑
public class AdminMemberController {

    @Operation(
      summary = "회원 상세 조회", // URL 우측 API 설명
      description = "관리자가 특정 회원의 상세 정보를 조회합니다.", // API를 펼치면 나오는 상세 설명
      security = @SecurityRequirement(name = "bearerAuth") // bearerAuth 인증 후 API 테스트 가능
    )
    @GetMapping("/{memberId}") // 상세 URL 매핑
    @PreAuthorize("hasAuthority('MEMBER_READ')") // 현재 로그인 사용자가 API 실행 시 필요한 권한 (필터에서 JWT 토큰을 파싱하고, Authentication 생성 시 세팅한 권한(authorities) 체크)
    @RateLimit(type = "general")
    public ResponseEntity<CommonResponse<AdminMemberDetailResponse>> getMemberDetail( // API 응답 예시 클래스 반환 설정. 클래스 내부 @Schema(example = "응답값 예시") 가 작성된 필드들을 모아서 JSON 형태로 표현
      @Parameter(description = "회원 ID", example = "1") // 파라미터 설명 및 입력값 예시 수동 추가
      @PathVariable Long memberId // 타입 + 이름으로 추론하여 파라미터 입력 폼 자동 추가
    ) {
      return ResponseEntity.ok(CommonResponse.success(adminMemberService.getMemberDetail(memberId)));
    }
}

컨트롤러에 어노테이션을 추가하여 스웨거에 보여질 내용들을 작성할 수 있습니다.

security = @SecurityRequirement(name = “bearerAuth”) 설정으로 Authorize 버튼이 API 문서 우측 상단에 표시되며,
버튼 클릭 시 나오는 팝업에 JWT 액세스 토큰을 입력하면 이후 요청들 헤더에 토큰이 자동으로 추가됩니다.

enum 파라미터 추가 방법

@RequestParam(required = false) MemberStatus status

컨트롤러 파라미터로 Enum 클래스를 받으면 파라미터 Selectbox 선택 폼이 자동 추가됩니다.

enum 클래스 작성 예시

package com.membership.member.domain.enums;

/**
 * 회원 계정 운영 상태
 * 인증 가능 여부와 운영 조치 판단 기준
 */
public enum MemberStatus {
    /** 정상 이용 상태 */
    ACTIVE,
    /** 장기 미사용 상태 */
    DORMANT,
    /** 운영 정지 상태 */
    SUSPENDED,
    /** 로그인 실패 누적 잠금 상태 */
    LOCKED,
    /** 탈퇴 처리 상태 */
    WITHDRAWN
}

파라미터 디스크립션 Available values : ACTIVE, DORMANT, SUSPENDED, LOCKED, WITHDRAWN가 자동 추가됩니다.

API 응답 예시 여러개 추가 방법

import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.ExampleObject;

@ApiResponses({ // 여러 응답 케이스를 묶는 컨테이너
  @ApiResponse(
    responseCode = "200", // HTTP 상태 코드 200에 대한 응답 예시
    content = @Content( // 미디어 타입 및 컨텐츠 명세
      mediaType = "application/json", // Media type 명시
      examples = { // 성공 응답 JSON 예시 여러개 작성 (Example selectbox로 선택 확인 가능)
        @ExampleObject( // 성공 응답 케이스 1
          name = "일반 회원", // Example Description
          summary = "USER 권한 회원 조회", // Examples 제목
          value = """
                  {
                    "success": true,
                    "data": {
                      "memberId": 1,
                      "email": "us***@example.com",
                      "role": "USER",
                      "status": "ACTIVE"
                    },
                    "error": null
                  }
                  """
        ),
        @ExampleObject( // 성공 응답 케이스 2
          name = "관리자", // Example Description
          summary = "ADMIN 권한 회원 조회", // Examples 제목
          value = """
                  {
                    "success": true,
                    "data": {
                      "memberId": 2,
                      "email": "ad***@example.com",
                      "role": "ADMIN",
                      "status": "ACTIVE"
                    },
                    "error": null
                  }
                  """
        ),
        @ExampleObject( // 성공 응답 케이스 3
          name = "잠긴 계정", // Example Description
          summary = "LOCKED 상태 회원", // Examples 제목
          value = """
                  {
                    "success": true,
                    "data": {
                      "memberId": 3,
                      "email": "lo***@example.com",
                      "role": "USER",
                      "status": "LOCKED"
                    },
                    "error": null
                  }
                  """
        )
      }
    )
  ),
  @ApiResponse(
    responseCode = "401", // HTTP 상태 코드 401에 대한 응답 예시
    content = @Content( // 미디어 타입 및 컨텐츠 명세
      examples = // 실패 응답 JSON 예시 1개 작성
        @ExampleObject( // 실패 응답 케이스
          value = """
                  { 
                    "success": false,
                    "data": null,
                    "error": {
                      "code": "AUTH_001",
                      "message": "인증에 실패했습니다."
                    }
                  }
                  """
        )
    )
  )
})
@GetMapping("/{memberId}")
public ResponseEntity<CommonResponse<AdminMemberDetailResponse>> getMemberDetailTest(@PathVariable Long memberId) {
  return ResponseEntity.ok(CommonResponse.success(adminMemberService.getMemberDetail(memberId)));
}

컨트롤러 상단에 @ApiResponses 어노테이션을 이용하여 응답값 예시를 수동으로 작성하는 방법입니다.
@Schema(example = “응답값 예시”) 방식보다 우선 적용되며, 다른 방식들도 존재합니다.

스웨거 설정 커스터마이징

SwaggerConfig 생성

@Configuration
public class SwaggerConfig {

  @Bean
  public OpenAPI openAPI() {
    return new OpenAPI()
      .info(new Info()
        .title("API 문서 상단 제목")
        .description("API 요약 및 설명")
        .version("v1.0.0"));
      // 모든 API에 bearerAuth 인증 방식 적용
      .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
      // bearerAuth 인증 방식 정의
      .components(new Components().addSecuritySchemes(
        "bearerAuth",
        new SecurityScheme()
          .type(SecurityScheme.Type.HTTP) // HTTP 인증 방식
          .scheme("bearer") // Bearer 토큰 방식
          .bearerFormat("JWT") // JWT 토큰 형식
          .description("JWT Access Token을 입력하세요. 'Bearer ' 접두사는 자동으로 추가됩니다.") // 인증 설정 팝업 안내 문구
      ))
      // 동일한 API 서버 리스트 (상단 Servers)
      .servers(List.of(
        new Server().url("https://운영서버도메인").description("Production server url"),
        new Server().url("https://스테이징서버도메인").description("Staging server url"),
        new Server().url("http://개발서버도메인").description("development server url")
      ));
  }
}

SwaggerConfig 파일은 /src/main/java/com.도메인/common/config 폴더에 위치할 수 있습니다.

최신 글