057 | API Documentation, Swagger, SpringRest

🎈 API Documentation

클라이언트는 HTTP request URL(또는 URI)을 통해 서버에 데이터를 요청한다. 이 때 클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해서 알아야 되는 요청 정보(요청 URL(또는 URI), request body, query parameter 등)를 문서화 한 것을 API 문서 또는 API 스펙(사양)이라고 한다.

API 문서는 개발자가 직접 수기로 작성할 수도 있지만, 개발중이거나 유지보수를 할 때 API가 수정될 수도 있고, 클라이언트에게 제공된 API 정보와 수기로 작성된 API 문서 정보가 다를 수 있기 때문에 비효율적이다. API 문서 자동화를 통해 API에서 생기는 에러 발생을 방지하고 작업 시간을 단축할 수 있다.

 

🧩 Swagger의 API 문서화 방식 - 애너테이션 기반

• • 애플리케이션 코드에 문서화를 위한 애너테이션들이 포함된다.
  • 가독성 및 유지 보수성이 떨어진다.
  • API 문서와 API 코드 간의 정보 불일치 문제가 발생할 수 있다.
  • API 툴로써의 기능을 활용할 수 있다.

🧩 Spring Rest Docs의 API 문서화 방식 - 테스트 케이스 기반

• • 애플리케이션 코드에 문서화를 위한 정보들이 포함되지 않는다.
  • 테스트 케이스의 실행이 “passed”여야 API 문서가 생성된다.
  • 테스트 케이스를 반드시 작성해야된다.
  • API 툴로써의 기능은 제공하지 않는다.

🎈 Swagger

• build.gradle > 의존성 추가

dependencies{
	implementation 'io.springfox:springfox-boot-starter:3.0.0'
}

• NPE 발생 > application.yml > 속성 추가

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

• 단점: @Api~애너테이션을 컨트롤러와 dto클래스에도 계속 추가해야함 → 코드 복잡
• 서버 실행 후 아래 url로 접속하면 swagger로 만들어진 API 문서를 확인할 수 있다.
  • http://localhost:8080/swagger-ui/index.html

🎈 Spring Rest Docs

Swagger는 실제 기능 구현 로직에 애너테이션이 추가되어 가독성도 떨어지고 불필요하게 코드가 길어지는 문제점이 있었는데, Spring Rest Docs는 코드가 실제 기능 로직이 아닌 test에 추가한다. 기능 로직에 에너테이션을 추가할 필요도 없고, API문서를 만들기 위해서는 테스트도 통과해야 만들어지기 때문에 오류 발생 확률이 줄어든다.

🧩 Spring Rest Docs 흐름

1. 테스트 코드 작성
   1-1. 슬라이스 테스트 코드를 작성한다.
   1-2. API 스펙 정보 코드를 작성한다.
2. test task 실행
   2-1. 슬라이스 테스트 코드 실행한다.
   2-2. 실행 결과 passed: 다음 작업 진행 / failed: 테스트 케이스 수정 후 passed할 때까지 테스트를 진행한다.
3. API 문서 스니핏 생성
   3-1. 테스트 케이스 실행결과가 passed이면 코드에 포함된 API 스펙 정보 코드를 기반으로 API 문서 스니핏이 .adoc 확장자를 가진 파일로 생성된다.
4. 스니핏을 포함한 API 문서 생성
5. .adoc 파일의 API 문서를 HTML로 변환
   생성된 API 문서를 HTML 파일로 변환한다.
   HTML로 변환된 API 문서는 HTML 파일 자체를 공유할 수도 있고, URL을 통해 해당 HTML에 접속해서 확인할 수 있다.

🧩 Spring Rest Docs 설정

plugins {
	id 'org.springframework.boot' version '2.7.1'
	id 'io.spring.dependency-management' version '1.0.11.RELEASE'

	// 확장자 .adoc를 가지는 AsciiDoc 문서를 생성해주는 Asciidoctor 사용하기 위한 플러그인 추가
	id "org.asciidoctor.jvm.convert" version "3.3.2"

	id 'java'
}

// ext 변수의 set() 메서드로 API 문서 스니핏 생성 경로 지정
ext {
	set('snippetsDir', file("build/generated-snippets"))
}

// AsciiDoctor에서 사용되는 의존 그룹 지정
configurations {
	asciidoctorExtensions
}

dependencies {
	// spring-restdocs-core / spring-restdocs-mockmvc 의존 라이브러리 추가
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'

	// spring-restdocs-asciidoctor 의존 라이브러리 추가
	asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
}

// :test task 실행 시 API 문서 생성 스니핏 디렉토리 경로 설정
tasks.named('test') {
	outputs.dir snippetsDir
	useJUnitPlatform()
}

// :asciidoctor task 실행 시 asciidoctorExtensions 설정
tasks.named('asciidoctor') {
	configurations "asciidoctorExtensions"
	inputs.dir snippetsDir
	dependsOn test
}

// :build task 실행 전에 실행되는 task
task copyDocument(type: Copy) {
	dependsOn asciidoctor
	from file("build/docs/asciidoc/")
	into file("src/main/resources/static/docs")
}

build {
	// :copyDocument task 먼저 실행
	dependsOn copyDocument
}

// :bootJar task는 어플리케이션 실행 파일을 생성
bootJar {
	enabled = true
	dependsOn copyDocument // :bootJar task실행 전에 :copyDocument task가 실행
	from ("${asciidoctor.outputDir}/html5") {
		into 'static/docs'
	}
}

🧩 Spring Rest Docs 테스트 케이스

@EnableJpaAuditing
@SpringBootApplication
public class Application {
		public static void main(String[] args) {
				SpringApplication.run(Application.class, args);
		}
}

@EnableJpaAuditing을 Application 클래스에 추가하게 되면 JPA 관련 Bean을 필요로 하기 때문에 @WebMvcTest 애너테이션을 사용해서 테스트를 진행 할 땐 @MockBean(JpaMetamodelMappingContext.class)를 Mock 객체로 주입해야 한다.

 

@WebMvcTest(MemberController.class)
@MockBean(JpaMetamodelMappingContext.class)
@AutoConfigureRestDocs
public class MemberControllerRestDocsTest {
    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private Service service;

    @MockBean
    private Mapper mapper;

    @Autowired
    private Gson gson;

    @Test
    public void rest() throws Exception {
        // given
        Dto dto = new Dto("cheese@cat.com", "cheese", "010-1212-1212");
        String content = gson.toJson(dto);

        Response response = new Response(
                        1L,
                        "cheese@cat.com",
                        "cheese",
                        "010-1212-1212",
                        new Stamp());

        given(mapper.Mocking1(Mockito.any(Dto.class))).willReturn(new Entity());
        given(service.Mocking2(Mockito.any(Entity.class))).willReturn(new Entity());
        given(mapper.Mocking3(Mockito.any(Entity.class))).willReturn(response);

        // when
        ResultActions actions =
                mockMvc.perform(
                        post("uri")
                                .accept(MediaType.APPLICATION_JSON)
                                .contentType(MediaType.APPLICATION_JSON)
                                .content(content)
                );

        // then
        actions
                .andExpect(status().isCreated())
                .andExpect(jsonPath("$.data.field").value(post.getField()))
                .andDo(document(
                        "identifier",
                        getRequestPreProcessor(),
                        ApiDocumentUtils.getResponsePreProcessor(),
                        requestFields(
                                List.of(
                                        fieldWithPath("field1").type(JsonFieldType.STRING).description("field1"),
                                        fieldWithPath("field2").type(JsonFieldType.STRING).description("field2")
                                )
                        ),
                        responseFields(
                                List.of(
                                        fieldWithPath("field1").type(JsonFieldType.OBJECT).description("field1"),
                                        fieldWithPath("field2").type(JsonFieldType.NUMBER).description("field2")
                                )
                        )
                ));
    }
}

public interface ApiDocumentUtils {
    static OperationRequestPreprocessor getRequestPreProcessor() {
        return preprocessRequest(prettyPrint());
    }

    static OperationResponsePreprocessor getResponsePreProcessor() {
        return preprocessResponse(prettyPrint());
    }
}

테스트가 통과하면 build/generated-snippets/스니핏 식별자 경로에 .adoc API 문서들이 생성된다.

🧩 스니핏을 이용한 API 문서화

만든 API 문서는 스니핏(조각 모음)이기 때문에 이 조각을 하나로 모을 템플릿 문서가 필요하다.

1. gradle 프로젝트에서 템플릿 문서 기본 경로인 src/docs/asciidoc에 index.adoc 파일을 생성하고 템플릿 문서를 작성한다.

= template documentation name
:sectnums:
:toc: left
:toclevels: 4
:toc-title: Table of Contents
:source-highlighter: prettify

writer <email>

version, date

***
== controller
=== handler method
.curl-request
include::{snippets}/identifier/curl-request.adoc[]

.http-request
include::{snippets}/identifier/http-request.adoc[]

.request-fields
include::{snippets}/identifier/request-fields.adoc[]

.http-response
include::{snippets}/identifier/http-response.adoc[]

.response-fields
include::{snippets}/identifier/response-fiedls.adoc[]

2. Gradle > Tasks > build > bootJar 또는 build로 빌드한다.

    src/main/resource/static/docs 디렉토리에 index.html파일이 생성된다.

3. html 파일 확인
    http://localhost:8080/docs/index.html

✅ Ref.

https://swagger.io/docs/specification/about/

About Swagger Specification | Documentation | Swagger

https://springdoc.org/

OpenAPI 3 Library for spring-boot