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

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.

主站蜘蛛池模板: 南安市| 青海省| 尚志市| 岳普湖县| 惠来县| 中卫市| 琼结县| 宿州市| 获嘉县| 忻州市| 南阳市| 长垣县| 大姚县| 呼和浩特市| 同德县| 清镇市| 和政县| 阳新县| 鄄城县| 稷山县| 普兰县| 浦县| 长丰县| 文登市| 东台市| 雅江县| 方城县| 高阳县| 延寿县| 綦江县| 永平县| 崇明县| 淮南市| 嘉荫县| 金门县| 西盟| 凭祥市| 时尚| 汉阴县| 兰坪| 友谊县|