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

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.

主站蜘蛛池模板: 武汉市| 明水县| 新昌县| 安远县| 双流县| 五家渠市| 彭阳县| 竹山县| 武川县| 化州市| 稻城县| 辽阳市| 来宾市| 尼勒克县| 德清县| 始兴县| 博野县| 新乡县| 梨树县| 中宁县| 宣汉县| 金川县| 合山市| 临安市| 寿宁县| 盘山县| 宁乡县| 文水县| 永善县| 兴化市| 永寿县| 重庆市| 措勤县| 普陀区| 永善县| 休宁县| 抚州市| 安化县| 蓝山县| 双牌县| 遂溪县|