[컴] SpringBoot v3 에서 openapi v2 사용

javadoc / 자동 문서 / swagger / api 문서 작성 /

SpringBoot v3 에서 openapi v2 사용

gradle 사용시 spring boot 에서 openapi spec의 문서를 만드려면 아래 build.gradle 처럼 springdoc-openapi-starter-webmvc-ui 를 추가하면 된다.

• implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

springboot v3 을 사용한다면 springdoc-openapi 2.x 를 사용해야 한다. springdoc-openapi-starter-webmvc-ui 는 springdoc-openapi-ui의 openapi-v2 이다.

• OpenAPI 3 Library for spring-boot
• v2에 대한 module 이름을 알 수 있다 : OpenAPI 3 Library for spring-boot

// build.gradle
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.1'
    id 'io.spring.dependency-management' version '1.1.4'
}

group = 'com.nsm'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '17'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'

    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
}

tasks.named('test') {
    useJUnitPlatform()
}

test

• OpenAPI 3 Library for spring-boot

내 springBoot server가 localhost:8080 에 떠있는 경우, 다음 경로로 가면 api 문서 화면이 보인다.

• http://localhost:8080/swagger-ui.html

json format은

• http://localhost:8080/v3/api-docs

disable

• OpenAPI 3 Library for spring-boot

다음 옵션 2개를 꺼주면 된다.

springdoc.api-docs.enabled=false
springdoc.swagger-ui.enabled=false

문서작성 annotation

일부는 자동으로 만들어주지만, 정확하지 않은 값으로 만들어준다. 명시적으로 api 문서에 값을 넣을때는 annotation 을 활용할 수 있다.

아래를 참고하면 된다.

• Swagger 2.X Annotations · swagger-api/swagger-core Wiki · GitHub

다만, @RequestBody의 경우 spring 의 annotation 과 겹쳐서 @io.swagger.v3.oas.annotations.parameters.RequestBody 등으로 사용해야 할 수 있다.

@PostMapping
@Operation(summary = "Create a User", description = "This can only be done by the logged in user.")
ResponseEntity<MyResponse> createUser(
        @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Created User object", 
          required = true, content = @Content(schema = @Schema(implementation = MyPostBody.class))) 
        @Valid @RequestBody MyPostBody user) {
    return ResponseEntity.status(HttpStatus.CREATED)
            .body(userService.createOne(user));
}

Reference

1. OpenAPI 3 Library for spring-boot