REST 경로 및 응답 문서화

Question

저는 스칼라 백엔드 및 JS 프론트 엔드를 사용하여 REST 응용 프로그램을 작성하고 있습니다. 이 경로는 직관적으로 논리, 편의 및 가독성과 일치하도록 설계되었습니다.

그러나 :

1. REST 경로 및 응답 본문 형식을 문서화하기위한 표준 관행은 무엇입니까?
2. 그런 문서를 생성하기위한 도구가 있습니까?

Answer 1

당신은 당신이에서 자동으로 생성하는 데 사용할 수있는 다양한 통합 도구의 여지가 자신감과 함께 예를 들어 Swagger 또는 IO-Docs

을 사용할 수 있습니다, 또한 위키 텍스트를 생성 할 것을 마련하기 쉬운 귀하의 코드 (일반적으로 일부 메타 데이터를 추가하여). 이러한 도구를 사용하여

시원한 것은 당신이 상호 작용하는 문서로, 자유에 대한 API 탐색기를 얻을 수 있습니다 것입니다!

Answer 2

일부, 희망, 유용한 힌트. HTTP 방법은

하는 예 요청을 만들기 어떤 URL에 사용되는

1. 문서 (가능한 경우, 복사 - 붙여 넣기 및 API와 함께 플레이하는 데 사용 할 수있는 일) 리턴 될 수
2. 문서의 모든 HTTP 응답을 (400 - 잘못된 요청, 500 - 서버 오류 201 - OK, 어떤 내용이 반환되지, (201) - 확인, 생성, 등)
3. (당신의 오류 코드 오류 설명) HTTP 코드가 일부 오류 메시지와 연관된되는 명확히
4. 주어진 요청에 대한 응답의 모양을 문서화합니다.이 필드는 항상 retu입니다. rned는 선택 사항입니다.

나는 같은 문서의 자동 생성을위한 모든 준비가 만든 도구를 모른다. 추가 태그를 사용하는 맞춤 JavaDoc 플러그인을 보았습니다.

/** 
* Description... 
* 
*/ 
@Path("/") 
class RestResource{ 

/** 
    * @JsonRequest {...} 
    * @JsonResponse {...} 
    * @Http 400 - bad request 
    * @Http 201 - ok, resource created 
    * 
    */ 
    @Path("/restMethod") 
    public void restMethod() 
//... 
} 

JavaDoc 형식으로 필요한 문서를 생성하고있었습니다. 등