Springdoc과 OpenAPI (어노테이션 활용법)

Tue, 17 Oct 2023 17:12:52 +0900

QueryString 처리 방식 비교

Spring에서 QueryString을 처리하는 두 가지 방식을 비교해보겠습니다.

방식 1: Object로 받기 (ParameterObject)

@Operation(tags = {"swagger"})
@GetMapping("/hello/parameters1")
public ResponseEntity<List<ResponseTest>> parameterObjectTest(ParameterObjectReq req) {
 ResponseTest response = new ResponseTest(req.email(), req.password(), req.occupation());
 return ResponseEntity.ok(List.of(response));
}

방식 2: 개별 파라미터로 받기 (@RequestParam)

@Operation(tags = {"swagger"})
@GetMapping("/hello/parameters2")
public ResponseEntity<List<ResponseTest>> parameterObjectTest2(
 @RequestParam(value = "email") String email,
 @RequestParam(value = "pw") String password,
 @RequestParam(value = "oq") OccupationStatus status
) {
 ResponseTest response = new ResponseTest(email, password, status);
 return ResponseEntity.ok(List.of(response));
}

모델 정의

ParameterObjectReq (Request DTO)

public record ParameterObjectReq(
 String email,
 String password,
 OccupationStatus occupation
) {
}

OccupationStatus (Enum)

public enum OccupationStatus {
 STUDENT,
 EMPLOYEE,
 UNEMPLOYED
}

두 방식의 차이점

일반적으로 request를 QueryString으로 받을 경우 @RequestParam을 사용하지만, 받는 인자가 많을 경우 첫 번째 방식처럼 QueryString을 Object 형태로 받을 수 있습니다.

@RequestParam vs ParameterObject

@RequestParam: 기본적으로 required = true로 설정되어 있어 request value를 필수로 받습니다.
ParameterObject: Spring에서 별도의 어노테이션 없이도 QueryString을 객체의 필드값에 자동으로 바인딩합니다. 하지만 required가 기본 설정되지 않아 null 값이 들어올 수 있습니다.

Springdoc에서의 ParameterObject vs @RequestParam 변환 비교

ParameterObject 사용 시

@RequestParam 사용 시

@ParameterObject 어노테이션 활용

ParameterObject를 Springdoc이 @RequestParam을 사용했을 때처럼 변환해주고 Required 여부를 표시하려면 다음과 같이 설정합니다.

코드 예제

@ParameterObject
public record ParameterObjectReq(
 @NotNull
 String email,

 @NotNull
 String password,

 OccupationStatus occupation
) {
}

@ParameterObject는 Springdoc 어노테이션으로, 여러 개의 QueryString을 Object 형태로 받을 경우 해당 클래스 위에 명시하면 @RequestParam처럼 인식하고 변환해줍니다.

JSR-303 지원

Springdoc은 JSR-303을 지원하며, 다음과 같은 validation 어노테이션을 사용할 수 있습니다

@NotNull
@Min, @Max
@Size
기타 validation 어노테이션

Springdoc 공식 문서에 따르면

This library supports

OpenAPI 3

Spring-boot (v1, v2 and v3)

JSR-303, specifically for @NotNull, @Min, @Max, and @Size

Swagger-ui

OAuth 2

GraalVM native images

변환 결과

ParameterObject도 @RequestParam으로 인식되도록 spec 파일이 작성되었고, @NotNull을 붙이지 않은 occupation에는 Required가 optional 형태로 표시됩니다.

좌측 이미지: @ParameterObject를 명시했을 경우 Springdoc이 인식하고 정상적인 spec으로 변환

Swagger2 → Swagger3 Annotations

Swagger2	Swagger3	설명
@Api	@Tag	클래스단에 swagger 리소스 표시(그룹화 시켜줌) `name` : 태그의 이름 `description` : 태그에 대한 설명
@ApiIgnore	@Parameter(hidden = true) @Operation(hidden = true) @Hidden	해당 어노테이션을 통해 파라미터를 swagger-ui 에서 숨길 수 있음. requestBody 나 ResponseBody 의 경우는 @JsonProperty(access = JsonProperty.Access.READ_ONLY) 를 사용
@ApiImplicitParam	@Parameter	단일 RequestParam 에 대한 설정 및 리소스 표시
@ApiImplicitParams	@Parameters	여러개의 RequestParam 을 설정
@ApiModel	@Schema	`description` : 한글명 `defaultValue` : 기본값 `allowableValues` : 허용가능한 값(열거형으로 정의가능할 경우 설정합니다)
@ApiModelProperty(hidden = true)	@Schema(accessMode = READ_ONLY)
@ApiOperation(value = “foo”, notes = “bar”)	@Operation(summary = “foo”, description = “bar”)	`summary` : api에 대한 간략 설명 `description` : api에 대한 상세 설명 `responses` : api Response 리스트 `parameters` : api 파라미터 리스트
@ApiParam	@Parameter	`name` : 파라미터 이름 `description` : 파라미터 설명 `in` : 파라미터 위치 (query, header, path, cookie)
@ApiResponse(code = 404, message = “foo”)	@ApiResponse(responseCode = “404”, description = “foo”)	`responseCode` : http 상태코드 `description` : response에 대한 설명 `content` : Response payload 구조 `schema` : payload에서 이용하는 Schema `hidden` : Schema 숨김여부 `implementation` : Schema 대상 클래스

여러 개의 request query params를 캡처하기 위해 객체를 사용하는 경우, 해당 메서드 인자에 @ParameterObject 어노테이션을 사용하세요
이 단계는 선택사항입니다: 여러 개의 Docket 빈이 있는 경우에만 GroupedOpenApi 빈으로 교체하세요

@Tag 어노테이션 활용

@Tag 어노테이션을 사용하면 다음과 같은 그룹핑이 가능합니다

Controller 단위로 그룹핑
Controller 내부의 메서드 단위로 그룹핑
@Tag에 명명한 이름에 따라 spec 파일로 전환 시 그룹핑 수행
OpenAPI Generator를 이용한 client code 생성 시 해당 이름으로 파일 생성

@Tag 중복 사용 시 주의사항

질문: 최상위 레벨에 @Tag로 그룹핑하고, 하위 메서드의 @Operation에서 다른 이름으로 tag를 설정하면 어떻게 될까요?

테스트 결과

최상위에 @Tag(name = "swagger")를 설정하고, postHello 메서드의 @Operation에서 tags = {"swagger123"}을 추가한 경우, 같은 엔드포인트가 다른 그룹으로 중복 생성됩니다.

문제점

이 상태에서 OpenAPI Generator를 사용하면 아래와 같이 중복된 client 코드가 생성되는 문제가 발생합니다.

권장사항: 특별한 경우가 아니라면 @Tag를 이용한 그룹핑은 Controller의 최상위에서만 사용하는 것을 권장합니다.

OpenAPI Generator Client Code 생성 시 파일명

Client 코드 생성 시 @Tag에서 명명한 이름 + -api가 postfix로 붙습니다. 이 부분을 커스터마이징하려면 Mustache 파일을 수정해야 합니다.

참고 자료

인증 관련 OpenAPI 스펙

OpenAPI는 다양한 인증 방식을 지원합니다. 주요 설정 항목은 다음과 같습니다.

type (인증 형식)

현재 API Key, HTTP, OAuth2, OpenID Connect 방식을 지원합니다. 참고: OpenAPI v2 스펙에서는 OpenID Connect 방식을 지원하지 않습니다.

지원되는 타입

http: Basic, Bearer 및 기타 HTTP 인증 체계
apiKey: API 키 및 쿠키 인증
oauth2: OAuth2 인증
openIdConnect: OpenID Connect 검색

주요 설정 항목

name: 인증 키 이름 (API Key 방식 사용 시 필요)
in: 인증 키의 위치 지정 (query, header, cookie 중 선택, API Key 방식 사용 시 필요)
scheme: 인증 방식 지정 (Basic 또는 Bearer, HTTP 인증 방식 사용 시 필요)
bearerFormat: Bearer 토큰 형식 (일반적으로 JWT 사용)
flows: OAuth2 플로우 타입 (implicit, password, clientCredentials, authorizationCode 중 선택)
openIdConnectUrl: OpenID Connect URL (OpenAPI v2 스펙에서는 OAuth2나 Bearer 토큰 방식으로 대체 권장)

@Deprecated 전략

API 버전 업데이트로 DTO 스펙에 변경이 있을 경우, 다음과 같은 단계적 전략을 사용합니다.

1단계: @Deprecated 표시

먼저 변경될 필드에 @Deprecated 어노테이션을 붙입니다.

public class UserDto {
 @Deprecated
 private String oldField;
 
 private String newField;
}

OpenAPI spec 상에도 해당 스키마의 필드에 deprecated가 표시되고, 프론트엔드에서 코드 생성 시 해당 필드에 deprecated 표시가 나타납니다. 이를 통해 프론트엔드 팀에게 곧 해당 필드가 제거될 것임을 미리 알립니다.

2단계: @Schema(hidden = true) 적용

프론트엔드에서 새로운 스펙으로 마이그레이션이 완료되면, 서버에서 해당 @Deprecated 필드에 @Schema(hidden = true)를 추가하여 더 이상 OpenAPI spec에 해당 필드가 생성되지 않도록 합니다.

public class UserDto {
 @Deprecated
 @Schema(hidden = true)
 private String oldField; // spec에서 제외됨
 
 private String newField;
}

3단계: 필드 제거

충분한 시간이 지난 후 해당 필드를 완전히 제거합니다.

이러한 단계적 접근 방식을 통해 프론트엔드와 백엔드 간의 안전한 API 버전 관리가 가능합니다.

OpenAPI Generator 정복하기

Mon, 16 Oct 2023 16:56:35 +0900

Swagger란?

Swagger는 OAS(OpenAPI Specification)를 위한 프레임워크로, API들이 가지고 있는 스펙을 명세하고 관리할 수 있는 프로젝트입니다. Swagger를 통해 REST API 서비스를 설계, 빌드, 문서화할 수 있습니다.

Swagger Tools

Swagger는 다음과 같은 주요 도구들을 제공합니다

Swagger UI: Swagger API 명세서를 HTML 형식으로 시각화하여 확인할 수 있도록 해주는 도구
Swagger Codegen: Swagger에 정의된 스펙에 따라 클라이언트 및 서버 코드를 자동으로 생성해주는 CLI 툴
Swagger Editor: Swagger 표준에 따른 API 설계서 및 명세서를 작성하기 위한 에디터

Springfox vs Springdoc

Springfox Swagger는 Spring 또는 Spring Boot를 사용하는 프로젝트에서 Swagger를 이용해 API 문서를 쉽게 작성할 수 있도록 도와주는 라이브러리입니다.

Springfox가 업데이트를 중단하는 시점에 Springdoc이 등장했으며, 활발한 업데이트가 이루어지면서 급부상하게 되었습니다. Springdoc 역시 Swagger 문서 작성을 지원하는 라이브러리로, 현재는 Springfox보다 더 권장되는 선택입니다.

Swagger Codegen vs OpenAPI Generator

Swagger는 SmartBear사의 트레이드마크이며, Swagger Codegen은 그 안에 포함되어 있는 프로젝트입니다.

OpenAPI Generator는 Swagger Codegen 프로젝트를 포크(fork)하여 시작된 커뮤니티 주도 오픈소스 프로젝트입니다. 현재 40명 이상의 상위 프로젝트 기여자와 Swagger Codegen의 창립 멤버들이 함께 참여하고 있습니다.

OpenAPI Generator License

OpenAPI Generator는 Apache License 2.0을 따르고 있습니다.

Apache License 2.0이란?

Apache License 2.0에 따라 다음과 같은 권리가 부여됩니다

누구나 해당 소프트웨어에서 파생된 프로그램을 제작할 수 있음
부분 또는 전체를 개인적 또는 상업적 목적으로 이용 가능
재배포 시 원본 또는 수정한 소스코드를 반드시 포함시키지 않아도 됨
단, Apache License 버전 및 표기는 반드시 포함해야 함 (Apache License로 개발된 소프트웨어임을 명확히 표시)

OpenAPI Generator의 탄생 배경

OpenAPI Generator의 공식 Q&A를 보면 프로젝트의 탄생 배경을 확인할 수 있습니다

버전 철학의 차이 Swagger Codegen의 창립 멤버들은 Swagger Codegen 3.0.0이 2.x의 철학과 너무 많이 다르다고 느꼈습니다. 두 개의 개별 브랜치(2.x, 3.x)를 유지 관리하는 오버헤드가 Python 커뮤니티에서 겪었던 것과 유사한 문제를 야기할 수 있다고 우려했습니다.
빠른 배포 주기 창립 멤버들은 사용자가 원하는 안정적인 배포 버전을 사용하기 위해 몇 달을 기다리지 않도록 더 빠른 배포 주기를 원했습니다.
- 주간 패치 배포 (Weekly patch releases)
- 월간 마이너 배포 (Monthly minor releases)
커뮤니티 주도 개발 커뮤니티가 주도하는 오픈소스 프로젝트 형식으로 진행하면 혁신과 신뢰성, 그리고 커뮤니티가 소유하는 로드맵을 확보할 수 있습니다.

위와 같은 이유들로 OpenAPI Generator 프로젝트가 탄생했습니다. OpenAPI Generator는 MySQL과 MariaDB의 관계와 유사한 느낌입니다.

Swagger Codegen에서 마이그레이션

공식 문서에 따르면, 기존에 Swagger Codegen 2.x 버전을 사용하고 있을 경우 OpenAPI Generator로 편리하게 마이그레이션할 수 있습니다. OpenAPI Generator는 Swagger Codegen 2.4.0-SNAPSHOT 버전을 기반으로 하고 있기 때문입니다.

자세한 마이그레이션 방법은 공식 가이드를 참조하세요

Migrating from Swagger Codegen | OpenAPI Generator

Swagger on 0AndWild_log

Springdoc과 OpenAPI (어노테이션 활용법)

QueryString 처리 방식 비교

방식 1: Object로 받기 (ParameterObject)

방식 2: 개별 파라미터로 받기 (@RequestParam)

모델 정의

두 방식의 차이점

@RequestParam vs ParameterObject

Springdoc에서의 ParameterObject vs @RequestParam 변환 비교

ParameterObject 사용 시

@RequestParam 사용 시

@ParameterObject 어노테이션 활용

코드 예제

JSR-303 지원

변환 결과

Swagger2 → Swagger3 Annotations

@Tag 어노테이션 활용

@Tag 중복 사용 시 주의사항

테스트 결과

문제점

OpenAPI Generator Client Code 생성 시 파일명

참고 자료

인증 관련 OpenAPI 스펙

type (인증 형식)

주요 설정 항목

@Deprecated 전략

1단계: @Deprecated 표시

2단계: @Schema(hidden = true) 적용

3단계: 필드 제거

OpenAPI Generator 정복하기

Swagger란?

Swagger Tools

Springfox vs Springdoc

Swagger Codegen vs OpenAPI Generator

OpenAPI Generator License

Apache License 2.0이란?

OpenAPI Generator의 탄생 배경

Swagger Codegen에서 마이그레이션

참고 자료