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

目錄

【引言】

【概述】

【超媒體應用狀態(tài)引擎】

【最活躍的技術(shù)】

【Open API】

【設計優(yōu)先：OpenAPI生成器】

【安裝】

Maven?安裝

手工安裝

源碼編譯安裝

Homebrew?安裝

Docker?安裝

NPM?安裝

使用案例：

確保運行環(huán)境正常

測試文件

生成客戶端API

生成go客戶端

結(jié)果截屏：

client.go

生成更多客戶端

userApi.java:

生成服務器代碼

生成Spring服務器

生成Golang服務器

main.go

api.go

生成Spring Boot服務

UserController.java

UserApi.java

支持的生成器類別

【代碼優(yōu)先：Swagger UI】

安裝程序庫：

代碼案例：

運行效果：

【RAML】

【API Blueprint】

【小結(jié)】

【參考資源】

【引言】

隨著REST API技術(shù)的興起，對于API的開發(fā)方法主要存在兩種："API設計優(yōu)先?"還是?"代碼優(yōu)先"。本文將通過學習API技術(shù)相關(guān)的概念，技術(shù)和相關(guān)工具來嘗試理解這類問題。

【概述】

API描述語言有時也被稱為接口描述語言（IDL）。結(jié)構(gòu)化的描述語言可以用來為人類程序員生成文檔；這樣的文檔可能比自由形式的文檔更容易閱讀，因為同一工具生成的所有文檔都遵循相同的格式約定。此外，描述語言通常足夠精確，可以自動生成各種軟件庫，從各種編程語言中訪問API。

如果用的好的話，?這項技術(shù)可以大大節(jié)省程序員創(chuàng)建API接口的工作。

【超媒體應用狀態(tài)引擎】

之前比較流行有兩種主要的描述語言：WSDL2.0（Web服務描述語言）和WADL（Web應用描述語言）。這兩種語言都沒有被業(yè)界廣泛采用來描述REST API，原因是這兩種語言的可讀性都很差，而且WADL實際上無法完全描述REST API。

構(gòu)建REST API的另一種方法被稱為超媒體應用狀態(tài)引擎-HATEOAS（Hypermedia as the Engine of Application State）。在這種方法中，客戶端不是通過文檔共享的靜態(tài)接口描述來編寫的，?而是被給予一組端點，并通過與這些端點的交互來動態(tài)地查詢API。HATEOAS是在Roy Fielding的博士論文《建筑風格與基于網(wǎng)絡的軟件架構(gòu)設計》中提出的。HATEOAS是REST API的最初設想，它將REST API與RPC機制區(qū)分開來。

【最活躍的技術(shù)】

圍繞著REST API?描述語言的社區(qū)非常活躍，格局在不斷變化中。根據(jù)統(tǒng)計，?該領域最活躍的技術(shù)是OpenAPI、RAML和API Blueprint。

【Open API】

Open API規(guī)范，最初被稱為Swagger規(guī)范，是一個機器可讀的接口文件規(guī)范，用于描述、生產(chǎn)、消費和可視化RESTful Web服務，最初是Swagger框架的一部分，在2016年成為一個獨立的項目，由Linux基金會的開源合作項目OpenAPI?倡議組織監(jiān)督。Swagger和其他一些工具可以通過一個接口文件生成代碼、文檔和測試用例。

基于Open API接口文件實現(xiàn)的應用程序可以自動生成方法、參數(shù)和模型的文檔。這有助于保持文檔、客戶端庫和源碼的同步。

OpenAPI規(guī)范是語言無關(guān)的。通過OpenAPI的聲明式資源規(guī)范，客戶端可以在不了解服務器實現(xiàn)或訪問服務器代碼的情況下理解和使用服務。

OpenAPI倡議組織維護了一個3.0版本規(guī)范的實現(xiàn)列表。SmartBear仍然以Swagger為其Open API工具的品牌。Swagger UI框架允許開發(fā)者和非開發(fā)者在一個沙盒UI中與API進行交互，從而了解API如何響應參數(shù)和選項。Swagger可以處理JSON和XML。

Swagger Codegen包含一個模板驅(qū)動的引擎，通過解析OpenAPI定義，生成不同語言的文檔、API客戶端和服務器存根。2018年7月，Swagger Codegen的頂級貢獻者William Cheng和其他40多位Swagger Codegen的貢獻者將代碼分叉到OpenAPI工具組織下的一個名為OpenAPI Generator的項目中。

API OpenAPI

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