어떻게 REST API를 문서화합니까?

Question

어떻게 REST API를 문서화합니까? 리소스가 무엇인지에 대한 문서가 아니라 요청에서 전송되는 데이터와 응답에서 데이터가 반환되는 대상은 무엇입니까? 무언가가 XML이 전송되고 XML을 반환 할 것을 기대한다는 것을 아는 것만으로는 유용하지 않습니다. 또는 JASN; 또는 무엇이든. 요청에서 전송 된 데이터와 응답에서 다시 전송 된 데이터를 어떻게 문서화합니까?

최상의 방법은 REST API와 데이터 요소를 문서화 할 수있는 Enunciate 도구입니다. 이 도구에 적합한 유형을 강조 표시하고이 도구를 제공하는 다른 도구를 놓치고 있습니까? 내 REST API를

소비자는

Answer 1

내 프로젝트에 결정했습니다 접근이하게 발음하다 등 모든 언어 파이썬, 자바, .NET,에있을 수 있습니다. REST API 문서의 사실상 표준 인 것처럼 보입니다.

Answer 2

당신을 도울 수있는 도구가 있는지, 최선의 방법이 무엇인지 (또는 둘 다) 묻는다면 잘 모르겠습니다.

다른 유용한 소프트웨어 문서와 마찬가지로 REST 문서에도 동일한 내용이 적용됩니다. 즉, 방문 페이지의 폭이 넓다는 것입니다 (예 : 자신이 수행하는 작업과 URI에 대한 설명이 포함 된 리소스 목록) 깊이있는 설명을 제공하는 드릴 다운 페이지가 있습니다. Twitter의 REST API는 문서화가 잘되어있어 좋은 모델이어야합니다.

Sample drilldown of one resource

Twitter API main page

내가 정말 드릴 다운 페이지를 좋아합니다. 각 매개 변수에 대한 설명과 함께 필요한 모든 매개 변수를 나열합니다. 지원되는 유형을 나열하는 사이드 바가 있습니다. 관련 페이지 및 동일한 태그가있는 다른 페이지에 대한 링크가 있습니다. 샘플 요청 및 응답이 있습니다.

Answer 3

내가 틀릴 수도 있지만 API를 문서화하기 위해 WSDL 및 XML 스키마와 비슷한 것을 원한다고 생각됩니다. Joe Gregorio의 게시물을 Do we need WADL에 게시 하시겠습니까? REST API에이 접근 방식을 사용하지 않는 이유에 대한 좋은 토론이 있습니다. 전체 아티클을 읽지 않으려면 API와 유사한 문서 (예 : WADL)로 충분하지 않으며 약한 인터페이스로 이어질 것입니다. 또 다른 좋은 기사는 Does REST need a description language입니까? 이 토론에는 좋은 링크가 많이 있습니다.

그의 게시물은하지 말아야 할 것에 대한 조언을 제공하지만 실제로해야 할 일에 대한 질문에는 실제로 대답하지 않습니다. REST에 대한 가장 중요한 점은 획일적 인 인터페이스라는 아이디어입니다. 즉, GET, PUT, POST 및 DELETE가 수행해야한다고 생각하는대로 정확하게 수행해야합니다. GET은 자원 표현, PUT 갱신, POST 작성 및 DELETE 삭제를 검색합니다.

큰 문제는 데이터를 설명하고 그것이 의미하는 바입니다. 언제나 XML 스키마 또는 비슷한 것을 정의하는 경로를 찾아 스키마에서 문서를 생성 할 수 있습니다. 개인적으로, 나는 유용한 모든 기계 문서를 찾지 못했습니다.

저의 겸손한 견해로는 최상의 데이터 형식에는 광범위하고 인간이 읽을 수있는 예제가 들어 있습니다. 이것이 의미론을 올바르게 설명하는 방법을 알고있는 유일한 방법입니다. 이 유형의 문서를 생성하려면 Sphinx을 사용하는 것이 좋습니다.

Answer 4

Enunciate를 사용해 본 경험이 있지만 훌륭하게 만들 수있는 클라이언트가 마음에 들지 않습니다. 반면에, 나는 지난 프로젝트에 swagger을 사용 해왔다. 내 요구에 맞을 것으로 보인다. 정말 멋진 시도 야.

UPDATE 2016년 3월 8일 : 당신이 자신감을 문서를 구축하게 발음을 사용할 수 있습니다처럼 보인다.
this을 참조하십시오.