目录

【引言】

【概述】

【超媒体应用状态引擎】

【最活跃的技术】

【Open API】

【设计优先：OpenAPI生成器】

【安装】

Maven 安装

手工安装

源码编译安装

Homebrew 安装

Docker 安装

NPM 安装

使用案例：

确保运行环境正常

测试文件

生成客户端API

生成go客户端

结果截屏：

client.go

生成更多客户端

userApi.java:

生成服务器代码

生成Spring服务器

生成Golang服务器

main.go

api.go

生成Spring Boot服务

UserController.java

UserApi.java

支持的生成器类别

【代码优先：Swagger UI】

安装程序库：

代码案例：

运行效果：

【RAML】

【API Blueprint】

【小结】

【参考资源】

【引言】

随着REST API技术的兴起，对于API的开发方法主要存在两种："API设计优先 "还是 "代码优先"。本文将通过学习API技术相关的概念，技术和相关工具来尝试理解这类问题。

【概述】

API描述语言有时也被称为接口描述语言（IDL）。结构化的描述语言可以用来为人类程序员生成文档；这样的文档可能比自由形式的文档更容易阅读，因为同一工具生成的所有文档都遵循相同的格式约定。此外，描述语言通常足够精确，可以自动生成各种软件库，从各种编程语言中访问API。

如果用的好的话， 这项技术可以大大节省程序员创建API接口的工作。

【超媒体应用状态引擎】

之前比较流行有两种主要的描述语言：WSDL2.0（Web服务描述语言）和WADL（Web应用描述语言）。这两种语言都没有被业界广泛采用来描述REST API，原因是这两种语言的可读性都很差，而且WADL实际上无法完全描述REST API。

构建REST API的另一种方法被称为超媒体应用状态引擎-HATEOAS（Hypermedia as the Engine of Application State）。在这种方法中，客户端不是通过文档共享的静态接口描述来编写的， 而是被给予一组端点，并通过与这些端点的交互来动态地查询API。HATEOAS是在Roy Fielding的博士论文《建筑风格与基于网络的软件架构设计》中提出的。HATEOAS是REST API的最初设想，它将REST API与RPC机制区分开来。

【最活跃的技术】

围绕着REST API 描述语言的社区非常活跃，格局在不断变化中。根据统计， 该领域最活跃的技术是OpenAPI、RAML和API Blueprint。

【Open API】

Open API规范，最初被称为Swagger规范，是一个机器可读的接口文件规范，用于描述、生产、消费和可视化RESTful Web服务，最初是Swagger框架的一部分，在2016年成为一个独立的项目，由Linux基金会的开源合作项目OpenAPI 倡议组织监督。Swagger和其他一些工具可以通过一个接口文件生成代码、文档和测试用例。

基于Open API接口文件实现的应用程序可以自动生成方法、参数和模型的文档。这有助于保持文档、客户端库和源码的同步。

OpenAPI规范是语言无关的。通过OpenAPI的声明式资源规范，客户端可以在不了解服务器实现或访问服务器代码的情况下理解和使用服务。

OpenAPI倡议组织维护了一个3.0版本规范的实现列表。SmartBear仍然以Swagger为其Open API工具的品牌。Swagger UI框架允许开发者和非开发者在一个沙盒UI中与API进行交互，从而了解API如何响应参数和选项。Swagger可以处理JSON和XML。

Swagger Codegen包含一个模板驱动的引擎，通过解析OpenAPI定义，生成不同语言的文档、API客户端和服务器存根。2018年7月，Swagger Codegen的顶级贡献者William Cheng和其他40多位Swagger Codegen的贡献者将代码分叉到OpenAPI工具组织下的一个名为OpenAPI Generator的项目中。