🛎️ 사건의 발단

스프링 백엔드 개발에서 문서화를 한다고 하면 일단 RestDocs 다.

여태껏 RestDocs만 써왔다.

Swagger 단점으로

1. 비즈니스 로직에 문서화 코드가 포함됨
2. RESTful API 의 자기증명을 지원해주지 못함

이런 단점이 있길래 RestDocs만 써왔다.

하지만 이번 팀플에서 프론트에서 Swagger 로 문서화 작업 해줄 것을 요청했다.

단점이 있는 것을 아는대도 단순히 보기 좋고, 쓰기 편하다고 Swagger 로 넘어가는 것은 좋은 방법이 아니라 생각했다.

그 때 팀원 중에 한 명이 Swagger 랑 RestDocs 를 섞어서 쓰는 문서화 방법이 있다고 알려줬다.

안 쓸 이유가 없었다.

🧬 구조

🔮 Swagger

Swagger 문서화 = SwaggerUI + Swagger

Swagger 코드는 openapi 코드로 변환되고, Swagger UI가 이 openapi 코드를 이용해서 시각화하는 방식

앞서 설명한 Swagger의 단점은 위의 Swagger 에 해당하는 이야기다.

다시 말해서, 우리는 SwaggerUI 만 쓰고, Swagger 는 버리면 된다는 이야기

흐름

Swagger와 RestDocs 를 함께 쓴다는 것은 이런 과정으로 진행된다.

1. RestDocs 로 문서화 스니펫을 만듬
2. 스니펫을 openapi3 으로 변환
3. Swagger UI에서 openapi3 를 활용해 html 로 표출

흐름 비교

🎁 필요한 거

그럼 필요한 게 무엇인지 나온다.

• Spring RestDocs
• restdocs-api-spec
• OpenAPI3
• Swagger UI

위 4개의 의존성을 추가해서 문서화를 해주면 된다.

📒Spring RestDocs

스프링에서 테스트와 문서화를 모두 지원하는 라이브러리다.

MockMvc, Rest Assured, WebTestClient 같이 각자 특색있는 방법을 통해서 테스트/문서화를 수행할 수 있다.

문서화를 수행하면 build 패키지 내에 스니펫이 만들어지게 되고,

이 스니펫을 활용해서 asciidoctor 가 html 파일을 만들어 렌더링하게 된다.

장단점

장점으로는

1. 테스트, 문서화를 동시에 수행 가능
2. RESTful API 의 자가증명 조건 만족 가능

단점으로는

1. 안 예쁨
2. 직접 스니펫을 선택해서 html 파일에 넣어줘야 함

Gradle

코드를 가져오긴 했는데

스프링 부트 사용하면 initializer 로 추가해서 하면 편하다.

dependencies {
		// RestDocs
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

코드

나는 MockMvc 로 문서화랑 테스트를 했다.

아래 보이는 것처럼

1. @AutoConfigureMockMvc, @AutoConfigureRestDocs 어노테이션으로 RestDocs MockMvc 테스트 설정을 해준다.
2. org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders 모듈의 메소드를 활용해서 테스트와 문서화 수행

@AutoConfigureMockMvc
@AutoConfigureRestDocs
@SpringBootTest
@Transactional
class ReviewRestControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private TestConfig testConfig;

    @Test
    @DisplayName("리뷰를 등록한 적 없다면 리뷰 등록 가능함을 응답한다.")
    void getReviewable_NotExistsReview_Reviewable() throws Exception {
        // Given
        final Long academyId = 1L;

        // When
        ResultActions perform = mockMvc.perform(get("/reviews/reviewable")
                .param("academyId", String.valueOf(academyId))
                .header(AUTHORIZATION_HEADER, BEARER + testConfig.getJwt())
                .accept(APPLICATION_JSON_VALUE)
                .contentType(APPLICATION_JSON_VALUE));

        // Then
        perform.andDo(print())
                .andExpect(status().isOk())
                .andExpect(content().contentTypeCompatibleWith(APPLICATION_JSON_VALUE))
                .andExpect(jsonPath("$.academyId").value(1L))
                .andExpect(jsonPath("$.reviewable").value(true))
                .andDo(document("get-reviewable",
                        preprocessRequest(prettyPrint()),
                        preprocessResponse(prettyPrint()),
				                requestHeaders(
				                        headerWithName("Authorization").description("JWT 토큰 (Bearer)")
				                ),
				                queryParameters(
				                        parameterWithName("academyId").description("학원 아이디")
				                ),
				                responseFields(
				                        fieldWithPath("academyId").type(NUMBER).description("학원 아이디"),
				                        fieldWithPath("reviewable").type(BOOLEAN).description("리뷰 등록 가능 여부")
				                )
                ));
    }

}

📕 restdocs-api-spec

Spring RestDocs 로 만들어진 스니펫을 OpenAPI3 스펙으로 만들어주는 라이브러리다.

참고로 스프링 버전, 스프링 부트 버전, RestDocs 버전, restdocs-api-spec 라이브러리 버전 중 안 맞는게 있으면 openapi3 스펙이 만들어지지 않는다.

Gradle

buildscript {
    ext {
        restdocsApiSpecVersion = '0.17.1'
    }
}

dependencies {
		// Spring Rest Api Spec
    testImplementation "com.epages:restdocs-api-spec-mockmvc:${restdocsApiSpecVersion}"
}

📗 OpenAPI3

openapi3 스펙을 만들어주기 위해서 추가적인 설정이 필요하다.

Gradle

openapi3 {
    servers = [
            { url = "http://localhost:8080" },
            { url = "https://서버url" }
    ]
    title = "플젝 제목"
    description = "플젝 설명"
    version = "버전"
    format = "json" // (json / yaml)
    outputDirectory = "src/main/resources/static"
    outputFileNamePrefix = "swagger"
}

Gradle openapi3 태스크를 만들어준다.

• servers
  • 이렇게 배열 형식으로 허용하려는 서버 도메인을 설정할 수 있다.
  • server = “url” 이렇게 한 서버만 설정할 수도 있다.
• format
  • 형식은 json과 yml 중에 선택할 수 있다.
• outputDirectory
  • openAPI3 스펙 결과가 저장되는 출력 디렉토리 경로를 지정하면 된다.
• outputFileNamePrefix
  • openAPI3 스펙 결과 파일의 파일명 prefix다.

📘 Swagger UI

이제 만들어진 openAPI3 스펙을 Swagger UI 를 통해 HTML 로 표출해주자.

Gradle

springfox 그룹꺼 쓰는 사람 있는데, 그 의존성 쓸 거면 버전 3이상은 써야 함

// Swagger UI
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

YAML 설정

콘텐트 타입을 json으로 설정했다.

위에 openapi3 설정에서 json으로 설정했기 때문이다.

swagger UI에 대한 기본 url 을 설정하고, 이 url에 대한 접근 url을 등록해주면 된다.

springdoc:
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    url: /v3/api-docs
    path: /docs/swagger

🔖 코드 작성법

기본적으로 위에 설명한 RestDocs 테스트 코드를 만들면 된다.

변경점이 거의 없기 때문.

1. 문서화 클래스 변경

   // Before
   import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
   
   // After
   import static com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper.document;

2. 문서화 코드 수정 (필수 아님; 안 해도 돌아감)

   // Before
   .andDo(document("post-like",
           preprocessRequest(prettyPrint()),
           preprocessResponse(prettyPrint()),
           requestHeaders(
                   headerWithName("Authorization").description("JWT 토큰 (Bearer)")
           ),
           requestFields(
                   fieldWithPath("academyId").type(NUMBER).description("학원 아이디")
           ),
           responseFields(
                   fieldWithPath("likeId").type(NUMBER).description("좋아요 아이디"),
                   fieldWithPath("memberId").type(NUMBER).description("학원 아이디"),
                   fieldWithPath("academyId").type(NUMBER).description("학원 아이디")
           )
   ));
   
   // After
   .andDo(document("post-like",
           preprocessRequest(prettyPrint()),
           preprocessResponse(prettyPrint()),
           resource(ResourceSnippetParameters.builder()
                   .tag(TAG)
                   .summary("좋아요 등록")
                   .requestHeaders(
                           headerWithName("Authorization").description("JWT 토큰 (Bearer)")
                   )
                   .requestFields(
                           fieldWithPath("academyId").type(NUMBER).description("학원 아이디")
                   )
                   .responseFields(
                           fieldWithPath("likeId").type(NUMBER).description("좋아요 아이디"),
                           fieldWithPath("memberId").type(NUMBER).description("학원 아이디"),
                           fieldWithPath("academyId").type(NUMBER).description("학원 아이디")
                   )
                   .build()
           )
   ));

🧮 결과 확인

설정한 swagger UI url 경로로 접근하면 된다.

http(s)://도메인/docs/swagger

http://localhost:8080/docs/swagger

위 yml 파일에서 설정한 것처럼 해당 url로 접근하면 swagger ui 를 볼 수 있는 url로 연결된다.