api문서 작성에 항상 고민이 많았음

웹에서 스웨거로 직접 작성하는 법 밖에 없나 싶었는데,

실은 스웨거도 코드 내에서 가능하더라 ㅋㅋㅋㅋ

아오...

코드스테이츠에서 알려준 건 Spring Rest Docs임

스웨거가 더 편한거 같긴 한데,

Spring Rest Doc은 테스트 코드를 통해 만들 수 있으니, 버그 잡기도 좋은 듯

일단 얘가 있어야 하나봄

저 문서 안에서 잘 세팅 해두고 빌드 때리면 알아서 api 문서를 만들어 주나봄

코드 작성

@WebMvcTest(MemberController.class)
@MockBean(JpaMetamodelMappingContext.class)
@AutoConfigureRestDocs
public class MemberControllerRestDocsTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private MemberService memberService;

    @MockBean
    private MemberMapper mapper;

    @Autowired
    private Gson gson;

    @Test
    public void postMemberTest() throws Exception {
        //given
        MemberDto.Post post = new MemberDto.Post("hgd@aa.com", "홍길동", "010-1111-1111");
        String content = gson.toJson(post);

        MemberDto.response response = new MemberDto.response(
                1L,
                "hgd@aa.com",
                "홍길동",
                "010-1111-1111",
                Member.MemberStatus.MEMBER_ACTIVE,
                new Stamp()
        );

        given(mapper.memberPostToMember(Mockito.any(MemberDto.Post.class))).willReturn(new Member());
        given(memberService.createMember(Mockito.any(Member.class))).willReturn(new Member());
        given(mapper.memberToMemberResponse(Mockito.any(Member.class))).willReturn(response);

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

간단하게 요론 테스트 코드를 작성했다. 내용물은 다 올릴라면 너무 많으니까 ㄴㄴ

아직 then 즉 확인(검증) 부분을 안만들었다. Spring Rest Docs는 여기서 작동함.

actions.andExpect(status().isCreated())
                .andDo(document(
                        "post-member",
                        getDocumentRequest(),
                        getDocumentResponse(),
                        requestFields(
                                List.of(
                                        fieldWithPath("email").type(JsonFieldType.STRING).description("이메일"),
                                        fieldWithPath("name").type(JsonFieldType.STRING).description("이름"),
                                        fieldWithPath("phone").type(JsonFieldType.STRING).description("휴대전화번호")
                                )
                        ),
                        responseFields(
                                List.of(
                                        fieldWithPath("data").type(JsonFieldType.OBJECT).description("결과 데이터"),
                                        fieldWithPath("data.memberId").type(JsonFieldType.NUMBER).description("회원 식별자"),
                                        fieldWithPath("data.email").type(JsonFieldType.STRING).description("이메일"),
                                        fieldWithPath("data.name").type(JsonFieldType.STRING).description("이름"),
                                        fieldWithPath("data.phone").type(JsonFieldType.STRING).description("휴대전화번호"),
                                        fieldWithPath("data.memberStatus").type(JsonFieldType.STRING).description("회원 상태"),
                                        fieldWithPath("data.stamp").type(JsonFieldType.NUMBER).description("스탬프 갯수")
                                )
                        )
                ));

어질어질해 보이는데 실제론 간단함.

.andDo() 에 작성 하는데,

document()를 불러와서 문서화 할거라고 알려줌

일단 이 api문서의 식별할 제목 같은걸 적고 ("post-member")
요청, 응답을 가져올건데
요청 필드는 이렇게 생겼고
응답 필드는 이렇게 생겼어!

라고 알려주는거임

드릅게 쓸게 많은데 그냥 스웨거 써도 되지 않을까

뭐 넣을 건지 설정

이걸 만들어 두고

= 커피 주문 애플리케이션
:sectnums:
:toc: left
:toclevels: 4
:toc-title: Table of Contents
:source-highlighter: prettify

hong Kill dong <kwj1830@naver.com>

v1.0.0, 2022.07.15

***
== MemberController
=== 회원 등록
.curl-request
include::{snippets}/post-member/curl-request.adoc[]

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

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

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

.response-fields
include::{snippets}/post-member/response-fields.adoc[]

=== 회원 정보 수정
.curl-request
include::{snippets}/patch-member/curl-request.adoc[]

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

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

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

.response-fields
include::{snippets}/patch-member/response-fields.adoc[]

이런 식으로 일일히 넣어줘야 한다.

결과

이런 식으로 꽤 보기 좋게 나온다.

목록도 볼 수 있고