(2) restdocs + openapi3 + swagger-ui 설정을 해보자 - 실전편

이 포스팅은 (1) restdocs + openapi3 + swagger-ui 설정을 해보자 - 설명편에서 이어지는 글입니다.

(준비) Swagger-UI 다운로드

https://github.com/swagger-api/swagger-ui/releases

Releases · swagger-api/swagger-ui

  위 링크에서 Swagger-ui를 다운로드를 받고 나면, 아래와 같이 진행중인 스프링 프로젝트의 `resources` 디렉토리 하위의 `static/swagger-ui`에 `dist` 폴더의 파일들을 넣어줍니다. 파일들을 넣은 후 아래의 이미지와 같이 필요 없는 파일들을 제외하고 필요한 파일들만 남겨줍시다.

resourcees/static/swwagger-ui

RestDocs 의존성 설치 및 gradle 스크립트 설정

  build.gradle에 ResetDocs 확장판의 의존성을 설치하고, 관련 스크립트를 추가해줍시다. 아래 스크립트는 구글링을 통해 여러 블로그에서 얻은 정보들과 AI 자문을 통해 얻은 정보들을 통해 본인이 자체 커스텀을 한 스크립트입니다.

// build.gradle
plugins {
	// 플러그인에 restdocs와 swagger 관련 라이브러리 id와 version 추가
    id 'com.epages.restdocs-api-spec' version '0.18.2'
    id 'org.hidetake.swagger.generator' version '2.18.2'
}

ext {
    RESTDOCS_API_SPEC_VERSION = "0.18.2"
}

dependencies {
    testImplementation "org.springframework.restdocs:spring-restdocs-mockmvc"
    testImplementation "com.epages:restdocs-api-spec-mockmvc:${RESTDOCS_API_SPEC_VERSION}"
}

// OpenApi3 설정
openapi3 {
    server = "http://localhost:8080"
    title = "OpenAPI"
    description = "OpenAPI Document"
    version = "0.0.1"
    format = "yaml"
}

def openapi3Path = "build/api-spec/openapi3.yaml"
def srcStaticDirPath = "src/main/resources/static/swagger-ui/"

tasks.register("copyToSwaggerUI") {
    dependsOn "openapi3"
    doLast {
        copy {
            from openapi3Path
            into srcStaticDirPath
        }
    }
}

tasks.register("copyTextToSecurity") {
    dependsOn copyToSwaggerUI
    doLast {
        def openapi3File = file(openapi3Path)
        def securityFile = file("src/test/resources/security.yaml")
        if (!openapi3File.text.contains("securitySchemes")) {
            openapi3File.append securityFile.text
        }
    }
}

clean {
    delete "$srcStaticDirPath/openapi3.yaml"
}

test.finalizedBy copyTextToSecurity

 

  위 스크립트를 요약하면 테스트(일괄 테스트, 부분 테스트 모두 포함) 이후 openAPI 문서가 다음 순서대로 진행이 됩니다.

1. 테스트를 진행합니다. restdocs 관련 코드가 포함된 테스트를 해야 `openAPI3.yaml` 파일에 변경사항이 반영이 됩니다.
2. 테스트 진행 후 `openapi3` -> `copyToSwaggerUI` -> `copyTextToSecurity` 태스크 순으로 자동 진행됩니다.
   
   1. `openapi3` 태스크는 `openAPI3.yaml` 파일을 빌드 폴더에 만드는 태스크입니다.
   2. `copyToSwaggerUI` 태스크는 `openAPI3.yaml` 파일을 맨 위에서 다운받았던 swagger-ui 폴더 내에 복사하는 태스크입니다.
   3. `copyTextToSecurity` 태스크는 `src/test/resources/security.yaml`의 파일의 내용을 복사하는 태스크입니다. `security.yaml` 파일의 내용은 다음과 같습니다.

  // src/test/resources/security.yaml
  // 아래 내용을 포함하면 Swagger에서 권한 설정이 가능해집니다.
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: JWT

 

  서버를 실행하고, 스웨거 링크(`http://localhost:8080/swagger-ui/index.html`)에 들어가면,  restdocs 관련 컨트롤러 테스트가 통과된 테스트들만 swagger에 기록되어 문서화가 될 것입니다!