REST docs 코드 스타일

identifier 통일

mockMvc.perform( ... )
// ...
                .andDo(document("subscription/save", // <-- 여기

identifier란 위와 같이 MockMvc andDo(document()) 에 전달하는 REST Docs 문서 조각에 대한 식별자입니다. 이에 대한 통일이 이뤄지지 않았는데, 아래 형식으로 통일하려 합니다.

컨트롤러 이름/컨트롤러 메소드 이름/{설명}

컨트롤러 이름과 컨트롤러 메소드 이름 은 필수고 설명 은 선택 사항입니다. '어떠한 이유로 실패했다', 혹은 '어떤 기준으로 필터링 한다' 등 API에 대한 부연설명이 필요한 경우 작성해주시면 됩니다.

Asciidoc 형식 통일

• 제목 통일
  • Path Parameters를 PathParameters, Path Parameter 등 으로 통일되지 않게 작성되어있는 부분을 통일합니다.
  • 통일 기준은 adoc snippet 파일 명 기준입니다. 만약 파일명이 .../request-fields.adoc 이라면, 제목은 Request Fields 로 작성합니다.
• 아래 adoc 스니펫은 API에서 사용되지 않을 경우를 제외하고 필수로 문서에 포함해야 합니다. (생략해도 큰 문제가 없다면, 생략합니다.)
  • 요청
    • http-request : HTTP Request Message
    • request-headers : Request 헤더 (requestHeaders()) (필요한 헤더가 Authorization 뿐이라면 생략합니다.)
    • path-parameters : URL 매개변수 (pathParameters())
    • request-parameters : URL 쿼리 스트링 (requestParameters())
    • request-fields : Request Body 각 필드에 대한 설명 (requestFields())
  • 응답
    • http-response : HTTP Response Message
    • response-fields : Response body 각 필드에 대한 설명
• 유효하지 않은 API 요청에 대한 문서화 시 Response에 대한 스니펫만 추가합니다.
• 그외 필요시 직접 adoc 문서에 텍스트로 부연설명 하면 됩니다.

request-body 와 response-body 는 각각 http-request 와 http-response 에 포함되므로 사용하지 않습니다. 또한, curl-request 와 httpie-request 도 사용할일이 없으므로 사용하지 않습니다.