One post tagged with "API문서"

안녕하세요, 집사의고민 백엔드 개발자 로지입니다. 이번 글에서는 저희 팀이 선택한 API 문서화 방법을 소개하고 어떻게 적용했는지 알려드리려고해요.

웹 애플리케이션 API를 구현하고 관리하게 되면 문서화에 어떤 기술을 활용할지 고민하게되는데요, 스프링 진영에는 다음 기술들을 주로 고려하는 것 같습니다.

• Spring Restdocs
• Swagger Generator

결론적으로, 이 둘 중 하나를 써도 되지만 저희 팀은 두 기술을 모두 활용해보기로 했습니다.

저희 팀은 먼저, 실제로 호출되는 API와 문서가 동기화되는 restdocs를 사용하기로 결정했습니다. 하지만 기존에 restdocs를 사용해본 경험이 있는 크루들은 restdocs의 asscidoc 이 swagger ui에 비해 화면/기능에 있어 실용성이 부족하다고 생각했습니다.

이 부분을 절충하기 위해, swagger generator에서 ui를 생성하는 기능만을 사용해 restdocs와 함께 사용해보는 것으로 결정하게 되었습니다.

필요한 도구들​

• restassured (인수테스트 도구): 저희 팀은 인수테스트를 수행해 restdocs를 발행합니다. 인수테스트에 restassured라는 http 클라이언트 테스트 도구를 사용합니다.
• restdocs (문서화도구): restassured 테스트를 진행하며 API의 정보를 adoc으로 발행합니다.
• restdocs-api-spec: restdocs에서 만들어준 adoc으로는 바로 swagger UI를 만들 수 없습니다. swagger ui를 발행할 수 있도록, adoc을 open api spec으로 변환해주는 도구입니다.
• gradle-swagger-generator-plugin : adoc에서 변환된 open api spec으로부터 swagger ui를 만드는데 사용할 도구입니다.

눈치채셨겠지만, 테스트부터 ui를 만드는 데까지 사용하는 순서대로 도구를 소개해드렸어요.

팀 개발 환경​

저희 팀은 다음 환경에서 작업을 진행했습니다!

• java 17
• Spring boot 3
• gradle 8.2.1
• intellij idea

흐름 보기​

자세한 설정까지는 아니더라도, 코드로 흐름을 본다면 이 글을 읽기가 더 수월할 것 같아 먼저 코드 조각들을 보여드리려고 합니다.

RestAssured로 테스트하는 코드​

@Test
void 파라미터에_이름을_넣고_요청한다() {
    // given
    var 요청_준비 = given(spec)
            .contentType(JSON)
            .filter(성공_응답_문서_만들기("hello-rosie-world-성공"));

    // when
    var 응답 = 요청_준비.when()
            .pathParam("name", "김크루")
            .get("/rosie/{name}");

    // then
    응답.then()
            .assertThat().statusCode(OK.value());
}

RestAssured 의 given, when, then 메서드를 사용해서 테스트를 진행합니다. 요청_준비 변수를 만드는 마지막줄에 filter 메서드에 RestDocs가 문서를 만들수 있도록 다음과 같이 명시해줍니다.

private RestDocumentationFilter 성공_응답_문서_만들기(String 제목) {
    return document(제목,
            API_정보.responseSchema(성공_응답_형식),
            pathParameters(parameterWithName("name").description("놀러와주신 분의 성함")),
            responseFields(
                    fieldWithPath("messages").description("환영의 단어들"),
                    fieldWithPath("ps").description("로지가 추가로 전하는 말").optional()
            ));
    }

이 테스트를 실행하면, restdocs가 adoc을 만들어줍니다.

open api 스펙으로 변환하기​

만들어진 adoc 파일은 다음과 같은데요, swagger UI에 활용할수 있도록 openapi 형식으로 변환해줍니다. openapi3 태스크를 실행하면 open api 3.0 스펙으로 생성돼요.

이렇게 만든 문서는 다음 화면에 대응될 예정입니다 :D

build.gradle 설정​

제가 사용한 그래들 스크립트입니다.

플러그인​

plugins {
    // 2. restdocs-api-spec 플러그인 추가
    id 'com.epages.restdocs-api-spec' version "${restdocsApiSpecVersion}"

    // 3. swagger-generator 플러그인 추가
    id 'org.hidetake.swagger.generator' version '2.18.2'
}

dependencies​

dependencies {
    testImplementation 'io.rest-assured:rest-assured'
    testImplementation 'org.springframework.restdocs:spring-restdocs-restassured'
    testImplementation "com.epages:restdocs-api-spec-restassured:${restdocsApiSpecVersion}"
    testImplementation "com.epages:restdocs-api-spec-mockmvc:${restdocsApiSpecVersion}"

    swaggerUI 'org.webjars:swagger-ui:4.11.1'
}

플러그인/태스크 설정​

• openapi3 설정
• 스웨거 ui 생성
• bootJar 설정

openapi3​

우선 restdocs-api-spec 의 설정을 해줄거예요.

openapi3 { // 4. open api 설정
    setServer("http://localhost:8080") // 4-1. 요청 보낼 서버의 baseUrl
    title = "로지 API Docs" // 4-2. 제목
    description = "로지네 API 명세서" // 4-3. 설명
    version = "0.0.1" // 4-4. api 문서의 버전
    format = "yaml" // 4-5. openapi 형식을 저장할 형식 (yaml/json)
}

코드와 대응하는 화면을 보여드릴게요.

GenerateSwaggerUI 설정​

그리고 나서, swaggerUI 를 만드는 태스크를 정의해줍니다. 자세한 설명은 주석을 참고해주세요.

tasks.withType(GenerateSwaggerUI) { // 5. swaggerUI 를 생성하는 task들은 전부
    dependsOn 'openapi3' // openapi3 이 실행된 이후에 실행되도록 설정
}

swaggerSources { // 6. swagger ui 생성에 필요한 source 설정.
    rosieProject { // ⭐️ rosieProject(이름은 프로젝트에 맞도록 변경) 라는 스웨거 ui의
        setInputFile(file("build/api-spec/openapi3.yaml")) // 소스 위치를 설정. (현재는 default 위치)
    }
}

// 7. rosieProject 에 대한 swagger ui를 생성하는 task.
generateSwaggerUIRosieProject {
    doLast { // ui 파일들이 생성되고 난 뒤
        copy { // 정적 리소스 디렉토리로 복사
            from outputDir.toPath()
            into "build/resources/main/static/docs" // jar 파일에 포한되려면 build/ 내의 위치로 설정해야합니다!
        }
    }
}

[2023.08.05 수정]

이전에 제가 실수로 src 하위에 (src/main/resources/static/docs) 파일을 복사하도록 했는데, 이렇게하면 jar 패키징에 생성한 ui파일들이 포함되지 않습니다~

bootJar 태스크 설정​

마지막으로, jar 패키징에 swagger ui가 포함될 수 있도록 설정해줍니다.

bootJar {
    dependsOn generateSwaggerUI
}

만약 위 스크립트로 안되면

bootJar {
    dependsOn tasks.withType(GenerateSwaggerUI) 
}

이렇게 해보시면 됩니다.

테스트 코드 작성​

RequestSpecification 설정​

RestAssured에서 Restdocs를 사용하기 위해서, 저는 다음과 같이 추상클래스에서 RequestSpecification 필드를 관리하게 되었습니다.

@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public abstract class AcceptanceTest {

    protected RequestSpecification spec;

    @LocalServerPort
    private int port;

    @BeforeEach
    void setUp() {
        RestAssured.port = port;
    }

    @BeforeEach
    void setUpRestDocs(RestDocumentationContextProvider provider) {
        RestAssuredOperationPreprocessorsConfigurer filter = documentationConfiguration(provider)
                .operationPreprocessors();

        this.spec = new RequestSpecBuilder()
                .setPort(port)
                .addFilter(filter)
                .build();
    }

}

restdocs가 설정된 RequestSpecification 사용하기​

restAssured 사용시, specification을 명시하지 않는 given() 을 이용하면 다음과 같이 매번 새로운 Specification을 사용합니다.

우리가 위에서 설정해준 spec 변수를 이용하기 위해서는 다음 방법으로 restAsscured를 사용해야합니다.

(1) given(spec)
(2) given().spec(spec)
(3) given을 사용하지 않는경우: when().spec(spec)

테스트 별로 생성할 문서 정의하기​

보통 restdocs를 asciidoc 으로 문서를 생성할 때는, 다음과 같이RestAssuredRestDocumentation.document 를 사용하는데요,

이 메서드를 restdocs-api-spec이 제공하는 wrapper 클래스의 메서드로 바꿔 사용합니다. (구현을 보면 많이 다를 건 없지만, 깃허브를 보면 openapi spec으로 변환할 때 편리함을 위해 제공한다고 합니다.)

private ResourceSnippetDetails API_정보 = resourceDetails()
            .summary("로지월드 들어가기 API")
            .description("로지 월드에 와서 환영을 받습니다.");

@Test
void 파라미터에_이름을_넣고_요청한다() {
    // given
    var 요청_준비 = given(spec)
            .contentType(JSON)
            .filter( // 여기입니다.
                                RestAssuredRestDocumentationWrapper.document("hello-rosie-world-성공", API_정보)
                        );

    // when
    var 응답 = 요청_준비.when()
            .pathParam("name", "김크루")
            .get("/rosie/{name}");

    // then
    응답.then()
            .assertThat().statusCode(OK.value());
}

같은 API에 대한 여러 요청(응답)​

같은 API에 대해서도, 여러 응답을 문서화해야하는데요. 이 작업은 별도의 작업이 필요하진 않습니다. 테스트별 document 메서드의 ResourceSnippetDetails 인자를 동일하게 설정해주면, 하나의 요청으로 간주하여 다음과같이 응답을 합쳐줍니다.

document() 사용법​

restdocs-api-spec 모듈은 코틀린으로 작성되어서.. 참고하시며 작업하시길 바라구요. 어쨌든, document() 메서드에는 많은 인자들이 들어갈 수 있는데요. 각 인자가 어떤 요소에 대응되는지 정리해봤습니다.

identifier: rest docs 생성 파일 디렉토리명​

document() 메서드의 첫번째 인자인데요, 이 아이는 restdocs에서 코드를 생성할 때 만들어지는 디렉토리의 이름이됩니다.

given(spec)
    .contentType(JSON)
    .filter(document("hello-rosie-world-성공", API_정보));

이렇게 설정하고, 테스트를 통과한다면 설정한 이름의 디렉토리에 adoc 파일들이 생성된 것을 확인할 수 있어요.

resourceDetails : API 정보​

API 정보는 ResourceSnippetDetails 클래스 로 정의합니다.

ResourceSnippetDefails API_정보 = resourceDetails()
    .summary("로지월드 들어가기 API")
    .description("로지 월드에 와서 환영을 받습니다.")

given(spec)
    .contentType(JSON)
    .filter(document("hello-rosie-world-성공", API_정보));

이 코드는 다음 화면에 대응돼요.

requestProcessor , responseProcessor: 요청/응답에 적용할 프로세서​

OperationProcessor 객체를 인자로 받습니다. OperationProcessor는 요청 또는 응답이 문서화되기 전에 적용하고 싶은 것을 정의할 수 있어요.

+) 프로세서는 다음과 같은 것들이 있어요: prettyPrint(), removeHeaders() 등..

snippeetFilters​

Function<List<Snippet>, List<Snippet>> 인데요, 변수명과 자료형을 보아 스니펫 리스트를 필터링하는데 사용하는 것 같습니다.

그러나 정확히 어떤 목적을 위한 변수인지는 모르겠습니다! 아시는 분은 알려주세요~ 저는 쓸 필요를 못느껴서 Pass~

snippets : 요청/응답 예시 등 API 문서 조각에 쓰이는 모든 것​

org.springframework.restdocs.snippet 에 정의돼있는 Snippet 객체를 가변 인자로 받아요.

저는 보통 다음과같이 요청 파라미터, 요청/응답 바디 Snippet을 활용하는 편입니다.

document("hello-rosie-world-성공",
  API_정보.responseSchema(성공_응답_형식),
  // 파라미터에 대한 snippet 생성
  pathParameters(parameterWithName("name").description("놀러와주신 분의 성함")),
  // 응답 바디에 대한 snippet 생성
  responseFields(
          fieldWithPath("messages").description("환영의 단어들"),
          fieldWithPath("ps").description("로지가 추가로 전하는 말").optional()
));

이외에도 Snippet은 여러가지 종류가 있는데요, 스니펫을 만들기 위해서는 지정된 정적 팩토리 메서드를 사용해야해서, 문서화가 필요한 대상의 키워드(ex. 쿼리파라미터, 헤더)로 restdocs 공식문서에서 검색해보시면 쉽게 찾을 수 있습니다 :D

전체 코드​

전체 코드는 깃허브에 올려뒀습니다. 글에서 조각으로 보면 복잡한 것 같기도한데, 한번에 보면 괜찮은 것 같아요.

https://github.com/kyY00n/restassured-restdocs-swaggerui

꽤 긴 튜토리얼이었는데요, 처음부터 꼼꼼히 읽기 보다는 초반에 소개드렸던 적용 흐름을 파악하시고, 디테일한 부분들은 공식문서와 함께 보는 것을 추천합니다 :D

여튼 읽어 주셔서 감사합니다. 올바르지 않거나 부족한 설명이 있다면 알려주세요! 여러분의 피드백을 격하게 환영합니다 :D

References

• https://github.com/ePages-de/restdocs-api-spec
• https://github.com/int128/gradle-swagger-generator-plugin
• https://docs.spring.io/spring-restdocs/docs/current/reference/htmlsingle/#getting-started