OpenAPI 간단 설정

- 4 mins
Swagger OpenAPI

OpenAPI

Swagger + Restdocs 의 장점을 한대 모은 OpenAPI Specification 을 사용하는 예시를 간략 정리했다.

start.spring.io에서 Spring REST Docs를 추가했다고 가정하고 추가한 요소에 대해서만 작성한다.

Dependency

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.1.3'
    id 'io.spring.dependency-management' version '1.1.3'
    id 'org.asciidoctor.jvm.convert' version '3.3.2'
    id 'com.epages.restdocs-api-spec' version '0.18.2'  // 추가
}

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

java {
    sourceCompatibility = '17'
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

ext {
    set('snippetsDir', file("build/generated-snippets"))
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
    testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.18.2'         // 추가**
}

tasks.named('test') {
    outputs.dir snippetsDir
    useJUnitPlatform()
}

tasks.named('asciidoctor') {
    inputs.dir snippetsDir
    dependsOn test
}

// 추가
openapi3 {
    server = "https://localhost:8080"
    title = "First Open API"
    description = "Open API Description"
    version = "0.1.0"
    format = "yaml"
}

bootJar{
   dependsOn(':openapi3')
}

// 추가
task copyTest {
    dependsOn("openapi3")
    copy {
        from "$buildDir/api-spec/openapi3.yaml"
        into "src/main/resources/static/docs/."
    }
}
Spring Boot version restdocs-api-spec version
3.x 0.17.1 or later
2.x 0.16.7

Swagger 정적 파일 다운로드

다운로드 : source link

소스 코드를 다운 받아 /dist 파일만 가져온다.

파일 삭제

파일 수정

first-image

접근 허용 및 View 설정

@Configuration
public class StaticRoutingConfigure implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
    }

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry
            .addViewController("/swagger-ui").setViewName("static/docs/swagger-ui.html");

    }
}

테스트용 컨트롤러

@RequestMapping("/items")
@RestController
public class ItemController {

    @GetMapping
    public ItemResponse getItem() {
        return new ItemResponse(1, "쌍쌍바", 1000,50);
    }
}

테스트 코드

class ItemControllerTest extends BaseIntegrationTest {

    @DisplayName("Get Item 테스트")
    @Test
    void getItem() throws Exception {
        // given
        mockMvc.perform(
                get("/items")
            )
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("쌍쌍바"))
            .andDo(document("item-get",
                builder()
                    .tag("테스트")
                    .summary("Get Item Test")
                    .description("아이템이 오는지 확인한다.")
                    .responseSchema(Schema.schema("MainResponse.Get"))
                ,
                preprocessRequest(prettyPrint()),
                preprocessResponse(prettyPrint()),
                responseFields(
                    fieldWithPath("id").type(JsonFieldType.NUMBER).description("아이디"),
                    fieldWithPath("name").type(JsonFieldType.STRING).description("이름")
                    , fieldWithPath("price").type(JsonFieldType.NUMBER).description("가격")
                    , fieldWithPath("quantity").type(JsonFieldType.NUMBER).description("수량")
                )
            ));
    }
}

swagger 접속

테스트 코드까지 모두 끝났다면 처음에 작성했던 task copyTest 를 작성하거나 build를 실행하자. 그리고 localhost:8080/swagger-ui 로 접속하면 아래와 같이 swagger 페이지가 완성된다. second-images

Gyuhwan Sim

Gyuhwan Sim

배움과 실천의 즐거움

comments powered by Disqus