Swagger + RestDocs

Web Testing환경을 쉽게 제공하지만, 테스트 안정적이지 못한 Swagger와 테스트 안정적이지만 Web Testing을 할 수 없고,asciidoctor 의 편집이 까다로운 restdocs의 장점을 합쳐 swagger의 Web 환경에서 Restdocs로 생성된 API 가이드를 확인하고 실행까지 시켜볼 수 있도록 하는 프로젝트

Git Repository Address

https://github.com/catsbi/oas_restdocs_documents

1.기존 Swagger, RestDocs 사용 방식과의 구별 점

• Swagger dependency 가 필요하지 않습니다.
  • Swagger의 경우 standalone으로 사용할 것이기에 별도의 의존성 필요가 없습니다.
• asciidoctor 를 따로 편집하지 않습니다.
  • 기존 restdocs로 생성되는 문서들을 종합하여 보여주는 asciidoctor 문서를 따로 편집하지 않습니다.추출된 OAS 파일을 Swagger 디렉토리로 복사하여 Swagger환경에서 노출되도록 합니다.
• spring REST Docs 의존성 변경
  • OAS 파일을 만들기 위해 독일 기업 epage 에서 만든 오픈소스 프로젝트인 restdocs-api-spec 을 사용합니다.

2. 구현 방법

구현 방법은 Maven 기준으로 진행하며, 다음과 같습니다.

1. Swagger-UI standalone 세팅

1. 다음 링크[ link ]에서 source를 다운받아 /dist의 내용을 프로젝트의 /resources/static/swagger-ui/ 경로에 집어넣도록 하며 이 때 폴더 구조는 다음과 같습니다.

2. 복사한 파일 중 이름 변경이 필요한 파일 수정과, 불필요한 파일을 제거한다.

   1. index.html → swagger-ui.html 이름 변경
   2. index.html 내부의 js, css경로를 static routing경로로 변경
   3. SwaggerUIBundle 메서드의 경로는 생성되어 복사 될 파일의 경로로 입력(ex: openapi-3.0.json or openapi-3.0.yaml)
   4. 불필요한 파일 삭제
      1. oauth2-redirect.html
      2. swagger-ui.js
      3. swagger-ui-es-bundle-core.js
      4. swagger-ui-es-bundle.js

3. Static Routing 설정하기

   @Configuration
   public class StaticRoutingConfig implements WebMvcConfigurer {
       @Override
       public void addResourceHandlers(ResourceHandlerRegistry registry) {
           registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
           registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/static/swagger-ui");
       }
   }
   

2. dependency 설정

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

    <asciidoctor.version>2.2.2</asciidoctor.version>
    <restdocs-api-spec.version>0.16.0</restdocs-api-spec.version>
    <restdocs-spec.version>0.21</restdocs-spec.version>
</properties>

<dependency>
    <groupId>com.epages</groupId>
    <artifactId>restdocs-api-spec</artifactId>
    <version>${restdocs-api-spec.version}</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>com.epages</groupId>
    <artifactId>restdocs-api-spec-mockmvc</artifactId>
    <version>${restdocs-api-spec.version}</version>
    <scope>test</scope>
</dependency>

<plugin>
    <groupId>io.github.berkleytechnologyservices</groupId>
    <artifactId>restdocs-spec-maven-plugin</artifactId>
    <version>${restdocs-spec.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <!--suppress MavenModelInspection -->
                <skip>${skipTests}</skip>
                <specification>OPENAPI_V3</specification>
                <name>[OAS + Swagger] Prototype</name>
                <description>restDocs로 생성되는 API 문서를 OAS(OpenApi Specification)을 이용해 Swagger로 표출하기</description>
                <format>JSON</format>
                <host>localhost:8080</host>
                <outputDirectory>${project.build.directory}/classes/static/swagger-ui/.</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>