API Documentation - Swagger

API 문서 :
。API를 개발자가 파악하여 사용하도록 명확한 가이드라인을 제공하는 문서
▶ Web application 개발 시 백엔드팀이 구축한 API를 swagger로 문서화하여 프론트엔드로 전달하여 API logic의 이해를 높이는 역할을 수행.
ex) 카카오 REST API Document

API 문서 명세 종류
。API의 문서화를 수행하기 위한 API Specification format
▶ API를 문서화하여 프론트엔드 등의 개발자가 쉽게 이해하고 테스트할 수 있도록함.

。API를 정해진 규칙에 맞게 .json or .yaml으로 정의됨

• Swagger Specification :
  。초창기 API 설계에 대한 API 문서화 표준
  
  。JSON , YAML을 지원.
  
  。현재 OAS ( Open API specification )으로 이름이 변경되어 대체
  ▶ Swagger라는 키워드는 Documentation tool의 일종으로 사용됨.
  
  
• OAS ( Open API Specification ) :
  。Swagger Specification 기반으로 발전된 형태의 현재 API 문서의 공식 표준
  
  。JSON , YAML을 지원.
  。누구나 사용하도록 API endpoint가 개방됨.
  ▶ 이를 통해 API Source code를 보거나 추가적인 API Document를 참고할 필요 없이 서비스를 이해할 수 있음.
  
  ▶ OAS의 명세로서 swagger를 통해 /v3/api-docs에서 다음처럼 출력

API Documentation Tool
。Swagger, RestDocs가 존재

• Swagger :
  。 API를 OAS 사양으로 API 명세를 정의하는 Open API Document를 자동으로 생성하는 프레임워크
  ▶ 어노테이션 기반이므로 활용하기 간편
  
  。Controller들을 Controller class 별로 자동으로 문서화.
  
  。프로젝트 내 API들을 정의하는 Controller를 자동으로 조회하여 api-docs라는 JSON 데이터를 생성 후 이를 기반으로 Swagger UI HTML 페이지를 생성.
  ▶ 실제 Swagger 문서는 api-docs를 기반으로 생성됨.
  
  。API 문서를 JSON / YAML 포맷으로 제공( /v3/api-docs )하거나 SwaggerUI를 통해 웹 상에서OAS API Document에 대한 시각화 HTML 페이지를 쉽게 조회 및 테스트 가능
  
  。Controller Class에 요청 & 응답 뿐만 아니라 Swagger의 API 문서화 기능을 작성해야하므로 SRP 원칙 위배
  ▶ 유지보수 가 어렵다.
  
  
• Swagger는 외부 공개용 API 문서에 적합하지 않은 개발자 전용 API 문서
  。프론트 - 백엔드 협업 용도로 사용되는 개발단계의 API 문서는 Swagger로 작성해야하며, 실제 end to end의 고객에게는 다음처럼 디테일하게 작성해야한다.
  
  。Swagger는 무조건 개발 서버에서만 사용해야하며, 운영서버에서 사용하면 안된다.
  ▶ API 호출을 통해 DB가 오염될 수 있으므로.
  
  。실제 고객에게 전달되어야 하는 API 문서는 따로 정의해야한다.
  ex ) 토스 API 문서
  
  
• application.yml 설정 Spring doc

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs # api-docs의 엔드포인트 지정 : localhost:8080/v3/api-docs
  swagger-ui:
    enabled: true
    path: /v3/api-docs # swagger ui의 엔드포인트 지정
    operations-sorter: alpha 
    display-request-duration: true 
	doc-expansion: full # list , full , none
    persist-authorization: true # false , off , on , true

springdoc: api-docs: enalbed: true
。api-docs를 자동 생성하도록 설정
▶ 기본적으로 true로 설정됨.

springdoc: api-docs: path: URL경로
。api-docs를 조회할 URL을 설정

operations-sorter : API 정렬 순서
▶ alpha : 알파벳 순 / method : HTTP Method 순

display-request-duration : 응답 예시에 응답시간 도출

doc-expansion: :
。처음 swagger 진입 시 API 문서 닫힘 / 펴진 상태로 도출하는 것을 설정
▶ full / list / none

persist-authorization : 인증정보 설정 시 인증을 유지하는 상태
▶ false, off, on, true

API 문서 생성 시 고려사항

• API 개발 시 클라이언트에게 전달해야하는 사항
  。 클라이언트가 다음 사항을 잘 알고 있어야 API를 사용 가능
  ▶ 다음 내용들을 Swagger를 통해 자동 생성
  
  。Resource ( 자원 )
  。Actions ( 수행 작업 )
  。Validation을 포함한 HTTP Request & Response에 사용되는 DTO 구조
  
  
• API Document가 최신으로 Up-to-date 되었는지, 코드와 정확하게 동기화되었는지 확인
  
  
• API Document가 일관된 형식을 유지하는지 보장
  。일반적인 기업에서는 수백개의 API가 존재하므로 사용자 입장에서 각자 일관된 형식으로 구성되어야 사용이 간편

API 문서 자동 생성
。Swagger를 활용하여 OAS( Open API Document )를 자동 생성

• springdoc-openapi 라이브러리 Dependency 추가하여 API 문서 생성
  springdoc-openapi : spring-doc 사이트
  。Spring 프로젝트를 기반으로 OAS API 문서의 자동 생성을 수행하는 라이브러리
  
  。 Application Runtime 시 @RestController, @RequestMapping, @GetMapping, @RequestParam 등의 어노테이션을 검사하여 API를 추론.
  
  。JSON, YAML 로 API 문서를 자동 생성
  ▶ Swagger UI와 자동으로 연동되어 웹에서 확인가능
  
  。springdoc-openapi v2.6.0 기준 OpenAPI 3, Spring-boot v3, swagger-ui를 지원.

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

。해당 의존성을 build.gradle에 정의 시 /v3/api-docs에 API 문서가 JSON으로 생성 및 Swagger UI를 통해 웹에서 API Document가 시각화 된 HTML 페이지를 조회가능

• Swagger UI : http://localhost:8080/swagger-ui/index.html
  。OAS의 API Document와 상호작용하여 Web UI로 볼 수 있는 기능
  ▶ /v3/api-docs의 API Document를 웹에서 시각화하는 HTML 페이지가 자동생성
  
  。Postman처럼 간편하게 API 테스트를 수행할 수 있음
  
  
  。Controller에서 사용되는 Request & Response DTO에 대한 Schema 정보도 조회가능
  ▶ 각 DTO의 field 우측 빨간색 별표는 null이거나 공백이면 안된다는 표시를 의미
  
  
  
• OpenAPI JSON
http://localhost:8080/v3/api-docs
  。OAS의 API 명세에 대한 정의를 JSON Format으로 제공
  ▶ 해당 페이지로 검색하는 경우 API에 관한 OpenAPI에 관한 정보를 JSON format의 API Document로 확인 가능
  
  。클라이언트가 해당 API의 Resource, Action, HTTP Message Structure에 관한 정보를 손쉽게 확인가능
  
  。openapi : OAS의 Version
  。info : API 문서의 metadata
  。servers : 테스트가 가능한 서버에 관한 정보
  。paths : 각 Controller에서 Mapping한 URL 엔드포인트에 대한 정보
  。components : API에서 사용하는 DTO의 schema 정보

Swagger 관련 어노테이션

。어노테이션 적용 시 Swagger UI와 /v3/api-docs의 json에 반영

@Tag(name = "지정할 컨트롤러클래스명")
。Swagger에 의해 표시될 Controller Class의 명칭을 임의로 설정

@Tag(name="멤버컨트롤러", description="설명")
@RestController
public class MemberController {}

▶ 컨트롤러 클래스 별로 정의 시 다음처럼 도출됨.

• @RequestBody(content = @Content(...))
  。해당 Controller의 API에서 예제 RequestBody를 입력하는 어노테이션
  
  
• @ApiResponse(responseCode = "HTTP상태코드" , description = "설명")
  。해당 Controller의 API에서 발생할 수 있는 가능성이 존재하는 HTTP Status Code 및 description를 정의하는 어노테이션
  ▶ 이후 Swagger를 통한 API 문서에서 생성됨
  
  。API 문서에는 @ResponseStatus뿐만아니라 해당 어노테이션의 Http Status Code도 추가됨
  
  
• @ApiResponses(value = { @ApiResponse(..) , @ApiResponse(..), .. })
  。선언된 Controller의 API에서 발생할 수 있는 여러 @ApiResponse들을 그루핑하는 어노테이션
  ▶ Controller는 200의 http status code 뿐만 아니라 500 등 해당 API 컨트롤러에서 발생할 수 있는 모든 CASE의 Http Status Code를 고려해야함
  
  。@ApiResponses 또는 @ApiResponse 들을 API들에 공통적으로 적용하는 경우 클래스 레벨 , 특정 API에만 선언 시 메서드 레벨에 선언하여 적용
  
  
• 활용 례

@RequestBody(
            content = @Content(
                    examples = @ExampleObject(
                            value = """
                                    {
                                      "email": "newgamer@test.com",
                                      "password": "mypassword123",
                                      "nickname": "새싹게이머"
                                    }
                                    """
                    )
            )
    )
    @ApiResponse(
            responseCode = "200",
            description = "회원가입 성공",
            content = @Content(
                    mediaType = MediaType.APPLICATION_JSON_VALUE,
                    examples = @ExampleObject(
                            """
                                    {
                                              "success": true,
                                              "message": "가입되었습니다.",
                                              "data": {
                                                "userId": 5,
                                                "email": "newgamer@test.com",
                                                "nickname": "새싹게이머",
                                                "role": "USER",
                                                "status": "ACTIVE",
                                                "provider": "LOCAL",
                                                "profileImageUrl": null,
                                                "createdAt": "2026-05-21T10:30:00",
                                                "lastLoginAt": null
                                              }
                                    }
                            """
                    )
            )
    )

▶ 다음처럼 표현 가능

Swagger 어노테이션 추상화
。복수의 Controller에서 동일한 Swagger 어노테이션을 사용하는 경우 추상클래스로 추상화하여 동일하게 상속받도록 구현할 수 있다.
▶ 어노테이션을 선언한 클래스 상속 시 해당 어노테이션을 선언한 것과 동일한 효과가 존재

// Swagger에 표시할 각 API의 HTTP Status를 API 전체에 일괄적으로 적용하기위해  클래스 레벨 선언
@ApiResponses(value = {
	@ApiResponse(responseCode="400", description = "유효성 검사 실패"),
	@ApiResponse(responseCode = "500", description = "서버 에러")
})
public abstract class SwaggerSupporter {
}

@Hidden
。API 문서내 포함하지 않을 클래스를 설정하는 용도로 사용하는 어노테이션
▶ 주로 @RestControllerAdvice 등이 선언된 클래스에 함께 선언

@Schema(name = "API문서에서 표현될 명칭")
。해당 DTO 또는 클래스가 API문서내에서 표현될 별칭을 지정하는 어노테이션
▶ 주로 인터페이스 또는 중첩 클래스로 구현된 DTO에 별칭을 부여시 주로 활용됨.

。주로 클래스 간 명칭 중복을 방지하는 용도로 사용
▶ 명칭 중복될 경우 덮어쓰기되므로.

• 주로 DTO의 Field에 선언하여 각 필드에 대한 Validation 등의 정보를 넣을 수 있음

		@NotBlank                       // Validation
        @Length(min = 10, max= 50)      // Validation
        @Schema(
                description = "추가될 아이템의 이름",
                example = "롱소드",
                requiredMode = Schema.RequiredMode.REQUIRED,
                minLength = 10,
                maxLength = 50
        )
        String name,

		@NotNull
        @Min(value = 1000L)
        @Schema(
                requiredMode = Schema.RequiredMode.REQUIRED,
                minimum = "1000"
        )
        Long price

▶ Validation 정보를 전달

▶ 다음처럼 DTO에 Validation이 추가됨

@Parameter(hidden=true)
。Controller의 매개변수에 선언하여 API 문서에 해당 매개변수를 표시할건지의 여부를 설정

@Operation
。메서드 레벨에서 선언하여 Swagger 문서에서 단위 Controller 별 API의 기능을 정의하는 어노테이션

。parameters 지정 시 DTO 같은 경우는 자동으로 Swagger가 식별하여 이름과 설명을 작성하므로 QueryString이나 PathVariable에 대해서만 해당 parameter를 작성하는게 좋은거같다.

	@Operation(
		summary = "비밀번호 변경", // API에 대한 요약
		description = "계정의 비밀번호 변경 관련 API", // API에 대한 상세설명
		parameters = {
			@Parameter(name = "accountId" , description = "계정 ID")
		}
	)
	ResponseEntity<ApiResult<Void>> updatePassword(
		UUID accountId,
		AccountRequest.UpdatePassword request
	);

• 인증헤더가 필요하다고 명시가 필요한 경우

@Operation(
            summary = "내 계정 정보 조회",
            description = "현재 로그인한 유저의 계정 정보를 조회하는 API",
            security = {
                    @SecurityRequirement(name = "bearerAuth")
            }
    )

DTO의 각 필드값에 대한 설명을 작성

public record PostDescription(
        @Schema(
                description = "게시물 제목을 입력",
                example = "게시물 제목1"
        )
        String title,
        @Schema(
                description = "게시물 내용을 입력",
                example = "게시물 내용1"
        )
        String content,
        @Schema(
                description = "게시물 작성자를 입력",
                example = "게시물 작성자1"
        )
        String authorName,
        @Schema(
                description = "게시물 작성일을 입력",
                example = "2026-06-11"
        )
        LocalDateTime createdAt
) implements Serializable {
}

@Content를 통해 Request Body와 Response Body의 예시를 지정하는 경우

• 요청 정의

@RequestBody(
            content = {
                    @Content(
                            mediaType = "application/json",
                            schema = @Schema(
                                    implementation = ProductsRequestDTO.class
                            )
                    )
            }
    )

• 응답 정의

@ApiResponse(
            responseCode = "201",
            description = "저장된 상품에 대한 내역",
            content = {
                    @Content(
                            mediaType = "application/json",
                            schema = @Schema(
                                    implementation = ProductsResponseDTO.class
                            )
                    )
            }
    )

▶ Products.class의 형식대로 DTO 설정