RESTful API 문서화를위한 표준 방법

RESTful API 문서화를위한 표준 방법

---

새로운 내부 웹 서비스를위한 RESTful API 사양을 작성 중입니다. 그것은하지 상당히 길고 매우 간단하지만, 그렇다고하더라도, 그것은 (실제적인 이유로 부정 행위에 반대 - 피 엄격한 REST를 사용하여 내 처음 PUT과 DELETE그들이 PHP에 통증이기 때문에, 등). REST 인터페이스를 문서화하기위한 표준 방법이나 모범 사례가 있는지 궁금합니다. 나머지 팀원들이 한눈에 이해하고 클라이언트를 작성하려는 모든 사람이 기본 코드를 이해하지 않고도 그렇게 할 수 있기를 바랍니다.

---

물론 REST API는 이상적으로 HATEOAS를 사용하고 하이퍼 텍스트 기반 (미디어 유형을 많이 사용함) 이어야 하지만 개발자가 작업 할 수있는 간단한 인간 친화적 인 문서를 갖는 것도 도움이됩니다.

다음과 같은 문서 생성에 도움이되는 몇 가지 특정 도구 :

• 멋진
  • REST API를 설명하기위한 공개 사양 [ github ]
  • 자동 생성 도구
    • 선적 서류 비치
    • API 용 코드
  • OpenAPI 이니셔티브에 기부하고 2015 년에 OpenAPI로 이름 변경
• 매 셔리
  • 오픈 소스 프로젝트 [ github ]
  • 생성 도구
    • 선적 서류 비치
    • API를위한 탐색 인터페이스
• 양봉장 및 API 청사진
  • 마크 다운 내 DSL에 API 설명 작성
  • 자동 생성 도구
    • 선적 서류 비치
    • 모의 서버
  • 루비 + 맥 개발자에 초점을 맞춘 것 같습니다.
• RAML
  • REST API를 설명하기위한 사양 [ github ]
• WADL
  • XML로 검색 가능한 API 문서를 작성하기위한 사양
  • WSDL과 WADL을 비교하는 토론
• APIgee
  • 문서화 기능이있는 상용 제품
• 3 스케일
  • 문서화 기능이있는 상용 제품
• Miredot
  • 상용 REST API 문서 생성기
  • 자바 특정

---

나는 꽤 좋은 http://apiary.io를 사용하고 있습니다. API 문서를 github로 내보낼 수도 있습니다.

---

여기 Roy의 게시물 에서 그는 다음과 같이 말합니다.

REST API는 리소스를 나타내고 애플리케이션 상태를 구동하는 데 사용되는 미디어 유형을 정의하거나 기존 표준 미디어 유형에 대한 확장 된 관계 이름 및 / 또는 하이퍼 텍스트 사용 마크 업을 정의하는 데 거의 모든 설명 작업을해야합니다. 관심있는 URI에서 사용할 방법을 설명하는 데 소비 한 모든 노력은 미디어 유형에 대한 처리 규칙 범위 내에서 완전히 정의되어야합니다 (대부분의 경우 기존 미디어 유형에 의해 이미 정의 됨).

---

좋은 ReST 문서는 미디어 유형과 미디어 유형 만 문서화하는 것을 의미합니다.

일반적인 시나리오에서는 다음과 같은 문서를 생성합니다.

Acme Corp XML 형식

링크 발견

다양한 리소스에 대한 링크는 책갈피 URI (일반적으로 서버의 루트 인 http://www.acme.org ) 에서 서버에 GET 또는 HEAD 요청을 실행하고 찾을 수있는 문서에 설명되어 있습니다 . HTTP 링크 헤더 :

Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml

여기서 rel부분은 링크 관계이고은 관계 xxx가 설정된 URI입니다.

링크 관계

이 문서는 다음 관계 이름을 정의합니다.

• http://rel.acme.org/services 링크 관계는 탐색 할 수있는 링크 목록을 설명합니다.
• http://rel.acme.org/customers 이 관계가 사용되는 링크는 고객 목록입니다.

미디어 유형

The application/vnd.acme.services+xml is a document with an xml serialization that describes a list of links an application may want to process.

<links>
 <link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>

The applcation/vnd.acme.customers+xml is a document with an xml serialization that describes customers.

Example documents:

<customers>
 <customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>

etc...

The point is to give a way to the developer to follow the links you define. First find the link to the index so they can get the list of things they can navigate to.

Once they discover that document, they discover that they can see a list of customers at a certain Uri, and can do a GET against it.

If they find a customer of interest, they can follow the link defined in /customers/customer/@href and issue a GET to retrieve a representation of that customer.

From there, your media type could embed actions that are available to the user, using more links. You also have the additional option of issuing an OPTIONS request on the resource to know if you can allow deleting the resource, or a PUT if you can save the document back after modification.

So a good documentation doesn't ever:

• give static links
• give interaction such as "you can issue POST on Customer with this media type and that will mean the move operation". The client should issue a POST against Customer only because your XML document has specified it that way.

The point of all this is to achieve minimum coupling between clients and servers. The client can be very smart in displaying and discovering resources (showing forms and god knows what else), but is totally dumb as to what the actual workflow is: the server decides.

---

At my company, we've been very happy using WADL, Web Application Description Language. Wikipedia describes it as: "an XML-based file format that provides a machine-readable description of HTTP-based web applications". I find raw WADL easy to write, read, and understand, and it maps directly to RESTful concepts. The official project provides a simple spec, XSD and RELAX NG schemata, and Java tools.

A number of tools and resources exist for working with WADL, including:

• wadl_stylesheets, XSLT stylesheets to create HTML documentation from WADL files
• Restlet, a Java framework for building RESTful servers and clients, includes a WADL extension

A tip: try including human-readable documentation, such as descriptions, concepts, getting started, usage tips, etc, in the WADL document's doc element by including HTML elements, using the XHTML namespace. It can make a big difference!

---

Initially, we went for static documentation of resources but just had to field too many questions. Eventually, we moved to using Live documentation pages using IO/Docs (actually a fork). Been working great.

---

You might find rest-tool useful.

It follows a language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs. It also provides a cook-book however it is in a very early stage, but its content is continuously growing.

The services you just described can be immediately used, so it is also good for experimenting.

---

To create understanding/documentation, heavyweight solutions aren't always needed. Examples of (great) heavyweight tools are: IO/Docs / Apigee (although great tools).

For tiny projects that already have a docchain setup (doxygen/phpdoc/phpdoctor/custom/etc) I use the following shellscript to just include the page in the full generated documentation:

https://gist.github.com/4496972

A demo: http://pastie.org/5657190

It just use custom comment-tags in your sourcecode. It can also be a nice starting point for documenting any sourcecode (language).

참고URL : https://stackoverflow.com/questions/898321/standard-methods-for-documenting-a-restful-api