Swagger + RestDocs 연동

yanju·2023년 2월 11일

10wonmoa

새로운 미션

Swagger와 RestDocs를 연동해보라는 미션을 받았다.

Swagger?

Swagger 는 REST API를 설계, 빌드, 문서화 및 사용하는 데 도움이되는 OpenAPI 사양을 중심으로 구축 된 오픈 소스 도구 세트입니다. - About Swagger Specification

Swagger를 사용하면 API를 테스트 할 수 있는 UI를 제공해준다.

RestDocs는 테스트를 실행하면서 성공하는지 실패하는지 확인하지만 Swagger는 문서 화면에서 API를 테스트 할 수 있다.

Restdocs에서 OpenAPI Spec 추출

Swagger UI 를 이용해 OpenAPI Spec 문서를 브라우저에서 확인할 수 있다.

이를 위해 Restdocs에서 OpenAPI Spec을 추출한다.

자세한 내용은 다음 github에서 확인할 수 있다.

https://github.com/ePages-de/restdocs-api-spec

build.gradle 추가

plugins {
		// 다음 내용을 추가
    id 'com.epages.restdocs-api-spec' version '0.16.0'
}

dependencies {
		// 다음 내용을 추가
    testImplementation 'com.epages:restdocs-api-spec-mockmvc:0.16.0'
}

// openapi 작업 추가
openapi3 {
    server = 'http://localhost:8080'
    title = 'Marbox API'
    description = 'Marbox API description'
    version = '1.0.0'
    format = 'yaml'

    copy {
        from 'build/api-spec'
        into 'src/main/resources/static/docs'
    }
}

Restdocs 문서화 로직 변경

기존에 Restdocs를 작성하는 코드는 다음 import를 사용한다.

`import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.;`*

이를 다음 import 구문으로 바꿔주면 된다.

import static *com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper*.*;

// import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*;
import static com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper.*;

위와 같이 설정하고 gradle openapi3를 실행하면 다음과 같이 OpenAPI Spec의 문서가 생성되어야 한다.

하지만 다음과 같이 테스트가 실패해버리고 오류가 생겨버렸다.

확인을 해보면 다음 예외가 발생한다.

com.epages.restdocs.apispec.ResourceSnippet$MissingUrlTemplateException

restdocs api spec 깃허브를 보면 다음 내용을 확인할 수 있다.

https://github.com/ePages-de/restdocs-api-spec

mockMvc로 요청을 보낼때 RestDocumentationRequestBuilders 패키지를 사용해서 요청을 보내야한다.

현재 패키지는 아래 사진처럼 MockMvcRequestBuilders 패키지를 사용한다. `org.springframework.test.web.servlet.request.MockMvcRequestBuilders`

이를 다음으로 바꿔준다.

`org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.`*

// import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*;

다시 openapi3를 하면 다음과 같이 잘 실행된다. 👍

Swagger UI 연동

이제 openapi3.yaml 파일을 Swagger UI 에 적용을 하면 된다.

build.gradle을 보면 openapi3 문서가 static/docs 로 복사가 되도록 설정해놨다.

도커로 swagger를 실행시키고 바로 openapi3 문서에 접근할 수 있도록 API_URL을 설정해준다.

marbox-swagger:
    image: swaggerapi/swagger-ui
    container_name: marbox-swagger
    ports:
      - 8081:8080
    environment:
      API_URL: http://localhost:8080/docs/openapi3.yaml