Springdoc OpenApi

Spring 애플리케이션을 위한 OpenAPI 3.0 문서를 자동 생성하는 라이브러리 REST API 의 API 문서를 자동화 해주는 도구입니다.

API 개발 문서화 도구

API 개발 문서화 도구는 API 엔드포인트, 요청, 응답 및 관련 정보를 문서화하여 개발자들에게 API 사용 방법을 제공하는 소프트웨어 도구입니다.

종류

•

Swagger

Swagger (OpenAPI)

REST API를 설계, 구축, 문서화 및 사용하는 데 도움이 될 수 있는 OpenAPI 사양을 기반으로 구축된 오픈 소스 도구 세트입니다.
https://swagger.io/docs/specification/about/

•

API 설계, 빌드, 문서화 및 테스트를 위한 통합 툴.

•

OpenAPI 표준을 준수하며, RESTful API를 쉽게 디자인하고 관리할 수 있음.

API Documentation & Design Tools for Teams | Swagger

Simplify API development for users, teams, and enterprises with our open source and professional toolset. Find out how Swagger can help you and get started today.

https://swagger.io/

SpringDoc OpenAPI Starter WebMVC UI

Maven Repository: org.springdoc » springdoc-openapi-starter-webmvc-ui » 2.7.0

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui/2.7.0

// Springdoc openapi
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'
SQL
복사

SwaggerConfig.java

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;


@Configuration
public class SwaggerConfig {
 
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("aloha") // 그룹명 설정
                .pathsToMatch("/**") // 경로 설정
                .build();
    }

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Test Proejct API")
                        .description("Test 프로젝트 API 입니다.")
                        .version("v0.0.1"));
    }

    
}
Java
복사

SpringDoc OpenAPI 주요 어노테이션

어노테이션	설명
@Operation	API의 작업(메서드) 수준에서 추가적인 정보를 제공하는 어노테이션입니다. HTTP 메서드에 대한 설명을 제공하고, 문서화되는 엔드포인트에 대한 추가 설명을 달 수 있습니다.
@ApiResponse	특정 HTTP 응답 코드에 대한 설명을 제공합니다. @ApiResponses와 함께 사용되며, 각 응답 코드에 대한 설명, 반환 타입 등을 설정할 수 있습니다.
	예시: @ApiResponse(responseCode = "200", description = "OK")
@Schema	모델 클래스의 필드에 대한 메타데이터를 제공하여 OpenAPI 스펙에 맞는 문서를 생성할 수 있게 해줍니다. 필드 이름, 타입, 설명 등을 추가할 수 있습니다.
	예시: @Schema(description = "User ID") private String id;
@Tag	API 엔드포인트를 태그로 그룹화하여 문서에서 관련된 엔드포인트를 묶을 수 있게 해주는 어노테이션입니다.
	예시: @Tag(name = "User", description = "Operations related to user")
@RequestBody	요청 본문에 대한 메타데이터를 문서화하는 데 사용됩니다. API의 요청 본문에 대한 설명을 추가할 수 있습니다.
	예시: @RequestBody(description = "User object that needs to be added")
@RequestParam	쿼리 파라미터에 대한 메타데이터를 문서화합니다. 파라미터의 설명, 필수 여부 등을 정의할 수 있습니다.
	예시: @RequestParam(description = "User ID", required = true)
@PathVariable	경로 변수에 대한 메타데이터를 문서화합니다. API 경로에서 변수로 사용되는 값에 대한 설명을 추가할 수 있습니다.
	예시: @PathVariable(description = "ID of the user")
@Deprecated	API가 더 이상 사용되지 않음을 나타내는 어노테이션입니다. API 문서에 "Deprecated" 메시지를 자동으로 추가할 수 있습니다.
	예시: @Deprecated @Operation(description = "This endpoint is deprecated and will be removed in the future")
@Hidden	OpenAPI 문서에서 해당 엔드포인트를 숨기고 싶을 때 사용합니다. 해당 API가 문서에 표시되지 않게 할 수 있습니다.
	예시: @Hidden