代碼優(yōu)先還是設(shè)計(jì)優(yōu)先？說說API開發(fā)技術(shù)（八）

@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或?qū)嶋HREST API所需的所有信息。雖然RAML是為REST API設(shè)計(jì)的，但它能夠描述不服從REST的所有約束的API（因此被稱為?"practically RESTful"）。它鼓勵(lì)重用，以最佳實(shí)踐結(jié)果為目標(biāo)。

一個(gè)例子：

一些亮點(diǎn)：

l??第7、12行：定義特征，在多處引用

l??第12行：Include一個(gè)文件

l??第13、14行：定義一個(gè)?"資源?"數(shù)據(jù)類型"/songs"；使用以前定義的特征。

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

l??第25、36行：MIME類型。

【API Blueprint】

API Blueprint是一種高級(jí)的API描述語言。你可以用它在API開發(fā)之前設(shè)計(jì)一個(gè)API，或者描述一個(gè)現(xiàn)有的API。

一個(gè)例子：

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

【小結(jié)】

在本文中，一共探討了三種API設(shè)計(jì)技術(shù)：?OpenAPI, RAML, API Bllueprint。我們重點(diǎn)從兩個(gè)方向?qū)W習(xí)了OpenAPI技術(shù)：

l??先設(shè)計(jì)API,?再從API配置文件生成客戶端和服務(wù)器端的代碼,也就是設(shè)計(jì)優(yōu)先的方法。

l??先寫出代碼實(shí)現(xiàn)，再從代碼生成API文檔，也就是代碼優(yōu)先的方法。

這兩種方法都有利有弊。在開發(fā)API時(shí)到底應(yīng)該選哪種方法？這主要取決于如下的因素：

l??誰會(huì)使用你的API？

l??他們的需求是什么？

l??API要解決什么問題？

l??誰來開發(fā)？

l??以后誰來維護(hù)？

在你選擇正確的API開發(fā)方法時(shí)，應(yīng)該先嘗試回答上面的問題。

歡迎討論。

API

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。