代码优先还是设计优先？说说API开发技术（八）

@Api(tags = "Member API") @CrossOrigin @Controller @RequestMapping(value = "/members", produces = MediaType.APPLICATION_JSON_UTF8_VALUE) public class MemberController { private MemberService memberService; public MemberController(@Lazy MemberService memberService) { this.memberService = memberService; } @ApiOperation(value = "Retrieves member information as filtered by an optional search string or filter request") @ApiResponses(value = { @ApiResponse(code = SC_OK, message = "ok") }) @ResponseBody @GetMapping(value = "") @ResponseStatus(HttpStatus.OK) public ResponseEntity> getAllMembers(@RequestParam(required = false) String searchString, FilterRequest filter) { return new ResponseEntity<>(memberService.getMembers(filter, searchString), HttpStatus.OK); } }

展开以后的效果：

【RAML】

REST API建模语言（RAML）是一种基于YAML的描述REST API的语言，它提供了描述REST或实际REST API所需的所有信息。虽然RAML是为REST API设计的，但它能够描述不服从REST的所有约束的API（因此被称为 "practically RESTful"）。它鼓励重用，以最佳实践结果为目标。

一个例子：

一些亮点：

l  第7、12行：定义特征，在多处引用

l  第12行：Include一个文件

l  第13、14行：定义一个 "资源 "数据类型"/songs"；使用以前定义的特征。

l  第15、19、37行：定义了HTTP方法。

l  第25、36行：MIME类型。

【API Blueprint】

API Blueprint是一种高级的API描述语言。你可以用它在API开发之前设计一个API，或者描述一个现有的API。

一个例子：

FORMAT: 1A # Categories API ## Categories [/categories] ### Create a Category [POST] + Response 201 ## Category [/category/{id}] + Parameters + id: 42 (required) ### Delete a Category [DELETE] + Response 204 ## Category Items [/category/{id}/items] + Parameters + id: 42 (required) ## Create an Item [POST] + Response 201

【小结】

在本文中，一共探讨了三种API设计技术： OpenAPI, RAML, API Bllueprint。我们重点从两个方向学习了OpenAPI技术：

l  先设计API, 再从API配置文件生成客户端和服务器端的代码,也就是设计优先的方法。

l  先写出代码实现，再从代码生成API文档，也就是代码优先的方法。

这两种方法都有利有弊。在开发API时到底应该选哪种方法？这主要取决于如下的因素：

l  谁会使用你的API？

l  他们的需求是什么？

l  API要解决什么问题？

l  谁来开发？

l  以后谁来维护？

在你选择正确的API开发方法时，应该先尝试回答上面的问题。

欢迎讨论。

API

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。