Spring/RestDocs

    Spring 2.7 버전대 RestDocs Cookie 문서화 방법(RestDocs 2.0.7)

    프로젝트 버전 SpringBoot 2.7.8 Spring Rest Docs 2.0.7 프로젝트를 진행하던 중, 인증과정에서 RefreshToken을 Cookie로 사용할 일이 있어 RestDocs로 Cookie를 문서화 하여야 했습니다. 이와 관련해서 RestDocs 공식문서, github 이슈, StackOverFlow글을 관련하여 찾아보았습니다. https://github.com/spring-projects/spring-restdocs/pull/592 https://docs.spring.io/spring-restdocs/docs/2.0.7.RELEASE/reference/html5/ https://stackoverflow.com/questions/39472873/how-can-i-document-th..

    RestDocs - Custom Error Code Enum 문서화

    RestDocs - Custom Error Code Enum 문서화 Enum으로 Custom ErrorCode 관리시 Enum 문서 자동화 방법 SpringBoot 버전 2.7.8 restdocs 버전 2.0.7 개요 데브코스에서 프로젝트를 하다 고민이 생겼습니다. 프론트엔드와의 협업간에 API 문서로 Spring RestDocs를 사용하고 있었고, API 사용 시 에러 응답에 대해 httpStatus 코드만으로는 클라이언트에 에러에 대해 디테일하게 설명할 수가 없어서 클라이언트가 개발과정 중 생긴 오류들에 대해 정확하게 알 수 있게 우리는 ErrorCode를 Enum으로 정의해서 내려주기로 하였습니다. public enum ErrorCode { ... NOT_MATCHED_COMMENT_AUTHOR(H..

    Restdocs fieldWithPath depth(list, array, 배열 문서화)

    RestDocs를 사용하여 필드를 문서화 때, 배열 depth가 길어지면 문서화하기 힘들어지는 경향이 있어 경험을 적어보려고 한다 https://jsoncrack.com/editor 라는 좋은 사이트를 사용하면 depth를 헷갈리지 않게 보기 좋다. (사랑해요 고마워요 스펜서) https://jsonformatter.org/ : json 이쁘게 보는 사이트 예제 1 - 2depth 다음과 같은 depth의 response를 작성해야 한다면 { "data": [ { "orderId": "20230130233846616HKuINK", "storeId": "store1", "orderStatus": "PAYMENT_COMPLETE", "nickname": "이디야화이팅", "items": [ [ { "item..

    Restdocs header 설정

    HTTP Headers 요청 및 응답 헤더에 대한 세팅을 할 수 있다. 각각 request-headers.adoc 과 response-headers.adoc 파일이 생성된다. Docs Reference this.mockMvc .perform(get("/people").header("Authorization", "Basic dXNlcjpzZWNyZXQ=")) .andExpect(status().isOk()) .andDo(document("headers", requestHeaders( headerWithName("Authorization").description( "Basic auth credentials")), responseHeaders( headerWithName("X-RateLimit-Limit")...

    REST Docs에 DTO Bean Validation 담기

    Bean Validation 사용시 Validation 정보를 담기 위한 커스텀 템플릿과 ConstraintDescriptions을 이용해서 Bean Validation 정보를 가져오는 방법에 대해 알아보자. 1. 커스텀 템플릿 만들기 스니펫 템플릿을 커스텀한다. test/resources/org/springframework/restdocs/templates/request-fields.snippet 파일 // request-fields.snippet ===== Request Fields |=== |필드명|타입|설명|필수값|Constraints {{#fields}} |{{#tableCellContent}}`+{{path}}+`{{/tableCellContent}} |{{#tableCellContent}}`..

    Restdocs pretty print, header 제거

    Restdocs pretty print - 이쁘게 출력하기 기본적으로 요청과 응답의 body가 텍스트로 쭉 나열된다. 크기가 작으면 상관 없지만, json 객체가 커진다면 제대로 확인하기 힘들어진다. pretty print 기능은 말 그대로 예쁘게 포메팅해준다. 스니펫을 모아 DocumentFilter를 만들때 넣어주면 된다. RestDocumentationFilter restDocumentationFilter = document( "simple-read", preprocessRequest(prettyPrint()), preprocessResponse(prettyPrint()), simplePathParameterSnippet(), simpleRequestParameterSnippet(), simpleR..

    RestDocs Custom - 문서 커스텀

    원하는 스니펫이 없을 경우 아예 스니펫을 새로 만들 수도 있다. Generating Custom Templated Snippets with Spring REST Docs에 잘 정리돼있다. RestDocs 공식문서 - https://docs.spring.io/spring-restdocs/docs/2.0.5.RELEASE/reference/html5/ 예제 - 원하는데로 커스텀 http-request.adoc, http-response.adoc, request-body.adoc, request.fields.adoc, response-body.adoc, response-fields.adoc 등 마음대로 스니펫을 커스텀할 수 있다. default 형식은 spring-restdocs-core /snippet/te..

    RestDocs 문서 분리 방법 - adoc, mustache

    RestDocs 공식문서 - https://docs.spring.io/spring-restdocs/docs/2.0.5.RELEASE/reference/html5/ 다음과 같이 User, Post 같이 여러 API들이 한 index.adoc 파일에 존재한다면 파일이 엄청 길어질 수 있어 분리하고 include 하여 사용할 수 있다. 먼저 분리할 목차에 마우스 커서를 올리고 맥 기준 option + enter를 누르면 다음과 같은 창이 나온다 Extract Include Directive를 클릭하면 인텔리제이가 해당 문서를 분리해준다. src/docs/asciidoc 위치로 해당 API를 빼주게 된다. 사용할 곳에서 include::filename.adoc[] 을 이용하면 된다. as-is .... 위에 더..

    Restdocs Enum 공통코드 문서화 방법 - Enum 문서화

    문서 작성 시 사용되는 타입에 enum이 없기 때문에 enum인 경우 따로 보기좋게 만들 수 있다. 예를 들어, Hobby와 Role의 Enum 클래스를 문서로 만들 수 있다. 먼저 interface를 정의한다. public interface DocsEnumType { String getType(); String getDescription(); } enum은 interface를 상속받아 메서드를 구현할 수 있는데, interface를 구현하게 되면, 다른 메소드나 생성자에서 인터페이스로 enum을 참조 할 수 있다. 만약 문서화가 필요한 Enum이라면 DocsEnumType 인터페이스를 상속받아야 하고, DocsEnumType을 상속받은 모든 enum은 getType()과 getDescription()을..

    RestDocs에서 Snippet 파일명 커스텀, Restdocs Link(링크) 걸기

    RestDocs에서 파일명은 일반적으로 request(response)-fields, request(response)-body 등의 규칙이 있다. Snippet 파일은 보통 src/test/resources/org/springframework/restdocs/templates/asciidoctor 아래에 커스텀하여 두는데, 이 때도 파일명을 규칙에 맞게 사용해야 requestFields() 메서드, responseFeilds() 메서드 등이 이해하여 커스텀 snippet을 읽어서 문서를 만들어준다. 이 때 규칙을 찾아보면, AbstractFieldsSninnpet이나 AbstractBodySnippet 이나, 생성자에서 첫번째 파라미터로 String type 또는 String name이라는 파라미터를 받..