Portfolio

SpringDoc OpenApi Custom Header 추가하는 방법 Swagger(Legacy)Swaager Annotation

SpringDoc OpenApi

[docs ] Springdoc-openapi

[ Github ] springdoc-openapi

[ Baeldung ] Documenting a Spring REST API Using OpenAPI 3.0

OpenApi : HTTP API 를 서술하는 정석적인 기준이라 할 수 있음

기존의 Springfox 라이브러리를 대체하는 springdoc

Swagger UI page : http://server:port/context-path/swagger-ui.html

OpenAPI description will be available at the following url for json format: http://server:port/context-path/v3/api-docs

Custom Header 추가하는 방법


@Configuration
class SwaggerConfig {

    @Bean
    // 이 부분이 UI 상에 나타나도록 하는 부분
    fun openAPI(): OpenAPI = OpenAPI()
        .components(
            Components()
                .addSecuritySchemes(
                    Header.CORP_TYPE, io.swagger.v3.oas.models.security.SecurityScheme()
                        .`in`(io.swagger.v3.oas.models.security.SecurityScheme.In.HEADER)
                        .type(io.swagger.v3.oas.models.security.SecurityScheme.Type.APIKEY)
                        .name(Header.CORP_TYPE)
                )
                .addSecuritySchemes(
                    Header.INTERNAL_API_KEY, io.swagger.v3.oas.models.security.SecurityScheme()
                        .`in`(io.swagger.v3.oas.models.security.SecurityScheme.In.HEADER)
                        .type(io.swagger.v3.oas.models.security.SecurityScheme.Type.APIKEY)
                        .name(Header.INTERNAL_API_KEY)
                )
                .addSecuritySchemes(
                    Header.USER_ROLE, io.swagger.v3.oas.models.security.SecurityScheme()
                        .`in`(io.swagger.v3.oas.models.security.SecurityScheme.In.HEADER)
                        .type(io.swagger.v3.oas.models.security.SecurityScheme.Type.APIKEY)
                        .name(Header.USER_ROLE)
                )
                .addSecuritySchemes(
                    Header.USER_ID, io.swagger.v3.oas.models.security.SecurityScheme()
                        .`in`(io.swagger.v3.oas.models.security.SecurityScheme.In.HEADER)
                        .type(io.swagger.v3.oas.models.security.SecurityScheme.Type.APIKEY)
                        .name(Header.USER_ID)
                )
        )
        .info(
            Info().description("""## Chumi API""").license(License().name("License LGU+")).title("추미 API")
        )
        .addSecurityItem(
		        // 이게 있어야 UI 상에 값이 들어갔을때 request에 같이 추가해서 보내게 됨
            SecurityRequirement()
                .addList(Header.CORP_TYPE)
                .addList(Header.INTERNAL_API_KEY)
                .addList(Header.USER_ROLE)
                .addList(Header.USER_ID)
        )



}

Swagger(Legacy)

개발한 REST API를 편리하게 문서화 해주고, 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트임

springfox-boot-starter(maven repository 에서 검색가능)를 gradle dependencies에 추가함으로 사용 가능함

springboot 2.6.4와 springfox-boot-starter 3.0.0 호환성 문제가 있음


java.lang.NullPointerException: Cannot invoke 
"org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()"
because "this.condition" is null

해당 에러 발생 시, application.properties 에 spring.mvc.pathmatch.matching-strategy =ant-path-matcher 요거 추가하면 동작함

Swaager Annotation

@Api 는 Controller 클래스에 대한 설명 붙일 수 있음

@ApiParam 은 메써드의 파라미터들에 대한 설명

메써드 위쪽으로

@ApiModelProperty → Dto 등의 클래스의 멤버변수에 대해 설명

@ApiOperation → 특정 endpoint에 대한 설명

@ApiResponse → 특정 메서드의 응답형태에 대한 서