官术网_书友最值得收藏!

Documenting contracts

Unlike soap style messages where the Web Services Description Language (WSDL) defines a robust contract between the consumer and service provider as an XML document, there was no such metadata exchanged when consuming a REST service until WSDL 2.0 was released.

Textual documentation still seems to be popular with developers to describe the available methods and entities. There is a NuGet package available for MS Visual Studio, which automatically generates help page content for Web API projects. It can be installed using the Package Manager Console using the following command: PM> Install-Package Microsoft.AspNet.WebApi.HelpPage.

Swagger, which is an open source product is also very popular among developers for generating interactive documentation and client SDK generation and discoverability. More information can be found at http://swagger.io/. Swagger appears to be Microsoft's tool of choice for API documentation as it has been adopted in many products in the Azure suite.

Another tool is RESTful API Modeling Language (RAML), which provides a contract first approach of modeling web APIs. This uses a derivative of YAML (YAML ain't markup language) and JSON to create a human- and machine-readable document. More information can be found at http://raml.org/index.html.

To help the consumers of the service, the messages should be self-descriptive, and you should be able to understand the requests and responses after spending minimal time using the service and reading the documentation. In the end, the URL structure has a large part to play in the overall usability of the service.

主站蜘蛛池模板: 光泽县| 平利县| 海盐县| 城市| 北京市| 舟山市| 郯城县| 东乡县| 郓城县| 汤阴县| 阿拉善左旗| 北安市| 顺平县| 沂水县| 民丰县| 临清市| 呼图壁县| 乐山市| 象山县| 陵水| 清远市| 武乡县| 儋州市| 阳西县| 于田县| 红原县| 扶风县| 沁源县| 巩留县| 山阳县| 射阳县| 吴堡县| 县级市| 新丰县| 阿鲁科尔沁旗| 吉水县| 道真| 胶州市| 阳新县| 如皋市| 改则县|