OpenAPI学习笔记

OpenAPI是一套API规范（ OpenAPI Specification ，OAS），用于定义RESTful API的接口。OpenAPI最初来自SmartBear的Swagger规范。

OpenAPI 目前的版本是3.0，当前Swagger和OpenAPI的关系是：

1. OpenAPI是一套规范
2. Swagger是实现OpenAPI规范的工具集，包括：
   1. Swagger Editor：允许你使用YAML语言在浏览器中编写规范，并实时查看生成的API文档
   2. Swagger UI：从OAS兼容的API动态生成一套Web的美观的API文档
   3. Swagger Codegen：用于生成OpenAPI的客户端库（SDK）、服务器桩代码、文档
   4. Swagger Parser：从Java解析Open API定义的独立库
   5. Swagger Core：一个Java库，用于创建、消费、使用OpenAPI定义
   6. Swagger Inspector：从现有的API生成OpenAPI定义、验证API的测试工具
   7. SwaggerHub：OpenAPI的API设计、文档平台

Swagger并非唯一支持OpenAPI的工具，到OpenAPI-Specification的GitHub页面可以看到相关工具的列表。

这是一个Node.js开发的工具，可以将Swagger 2.0转换为OAS 3.0，执行下面的命令安装：

调用格式： swagger2openapi source-spec.json [options]

常用选项说明：

通过某些工具，可以从既有代码中生成Swagger API文档。

该工具能够将Go Annotations转换为Swagger 2.0文档，为多种流行的Go Web框架（例如Gin）提供了插件，从而快速和既有Web项目集成。

执行下面的命令安装到GOPATH下：

在项目根目录，使用 swag init命令可以解析Go代码中的注解并且生成docs目录、docs/docs.go。你需要提供General API annotations，如果这些注解没有存放在根目录的main.go文件中，需要用 -g来指定Go文件路径：

使用swag init命令之后，你需要导入生成的docs包以及swaggo的另外两个包：

General API annotations可用字段：

示例：

swag init生成的docs包，导出了变量 SwaggerInfo，通过此变量你可以编程式的设置各种字段（和上面这种注释方式等效）：

为了在当前Web服务（的HTTP服务器）中查看API文档，需要注册路由，以gin为例： 

要生成API，你需要在控制器代码中添加 API Operation annotations。这些注解需要加在controller代码中，所谓controller代码，就是包含所有路由处理函数的包，以gin为例：

这些注解仅仅影响生成的Swagger API文档，不会对Web服务的逻辑产生任何影响。

运行Web服务，可以在http://localhost:port/swagger/index.html查看Swagger 2.0 API文档。访问/swagger/doc.json可以获得JSON格式的API

OAS是REST API的描述格式，在一个OpenAPI文件中，你可以定义完整的接口规格，包括：

1. 可用API端点列表，针对每个端点允许的操作
2. 操作的输入、输出参数
3. 身份验证方法
4. 附属信息，包括使用条款、License

关于OAS的编写，需要注意：

1. 可以用YAML、JSON两种格式编写
2. 所有关键字都是大小写敏感的

下面的API引用上述Schema：

OAS中的所有API端点，相对于Base URL，假设Base URL为https://api.example.com/v1则端点/users的访问路径为https://api.example.com/v1/users。

Open API 3.0允许在servers数组中声明多个Base URL。

API服务器的URL中，可以包含变量：

你可以在路径级别，甚至操作（方法） 级别，覆盖servers数组：

servers数组中的URL可以是相对URL，这种情况下，URL相对于提供OpenAPI定义的Web服务器。

举例来说，如果Open API定义存放在http://localhost:3001/openapi.yaml，则servers元素/v2解析为http://localhost:3001/v2 

请求或者响应的媒体类型，在content元素下声明：

可以指定多种媒体类型：

如果需要为多种媒体类型指定相同的Schema，可以使用 */*或者 application/*这样的通配符： 

在OAS中，路径即端点（资源），操作即HTTP方法。

路径可以包括路径变量，例如：

路径的description支持多行文本，还允许使用Markdown语法。

OpenAPI 3.0支持的HTTP方法包括：get, post, put, patch, delete, head, options,  trace。每个路径可以支持多个操作。

OpenAPI 3.0支持通过路径、查询字符串、请求头、Cookie传递参数。对于POST/PUT/PATCH请求，还可以通过请求体传递数据。

这种参数不得定义在路径中，下面是错误的用法：

下面则是正确的用法：

你可以为操作指定一个标识符：

此标识符必须在OAS中是唯一的。 operationId的使用场景包括：

1. 某些代码生成器使用operationId生成对应的方法名

参数需要定义在operation或path的parameters字段下。每个参数包括名字、位置、数据类型（通过schema或content定义）等属性。

参数可以通过以下HTTP元素传递：

1. 路径参数
2. 查询参数
3. 请求头参数
4. Cookie参数 

路径参数可以是数组，或者对象。这种参数在URL中的串行化形式可以是：

1. 路径风格展开，分号分隔，示例： /map/point;x=50;y=20
2. 标签展开，点号前缀，示例： /color.R=100.G=200.B=150
3. 简单形式，逗号分隔，示例： /users/12,34,56

具体使用哪种串行化风格，通过style、explode关键字指定。

这是最常见的参数形式，出现在URL的?后面。

RFC 3986规定 :/?#[]@!$&'()*+,;=为URI特殊字符。如果查询参数中包含这些字符，必须以%HEX形式编码。

使用default关键字可以为optional参数提供默认值：

要描述复杂参数的内容，可以使用schema或者content。这两个关键字是互斥的，用于不同的场景下。

大部分情况下，可以考虑使用schema，使用schema可以描述原始类型、串行化为字符串的对象、简单数组。对象、数组的串行化方法在style、explode关键字中定义：

style、explode无法满足的复杂串行化需求，可以使用content：

可以为某个参数指定可选值的集合，这些值的类型必须和参数类型匹配：

常量参数 —— 仅仅包含一个枚举值的参数：

OpenAPI 3.0允许仅仅有名字，而没有值的参数，在URL中表现为 /path?parm的形式：

你也可以在schema中声明nullable属性：

可以将一个参数标记为已经废弃：

所谓公共参数，即一个path下，所有方法都使用的参数定义：

OpenAPI支持以多种身份验证方式保护API：

1. 基于Authorization头的身份认证：
   1. 不记名令牌（Bearer）
   2. 基本认证
2. 请求头、Cookie、查询字符串中的API Key
3. OAuth2
4. OpenID连接发现

为方法添加security字段：

引用Schema：

本地引用： #/components/schemas/user

远程引用：

1. 当前服务器下其它文件： $ref: 'document.json'
2. 文件中的元素： $ref: 'document.json#/myElement'
3. 其它服务器中的元素： $ref:  http://path/to/your/resource.json#myElement

OpenAPITools/openapi-generator项目，用于从OpenAPI Spec（2和3版本）自动生成客户端库、服务器代码存根、文档以及配置文件。

openapi-generator广泛的支持各种常用语言和框架，对于Go来说，支持的Web框架包括Gin、Echo等。

用于生成OpenAPI 3.0的Go样板代码，以Echo为默认的Web框架。该库致力于尽量的简单化，而非通用化，它不会为所有OpenAPI Schemas生成强类型的Go代码。

默认情况下oapi-codegen会生成包括客户端、服务器、类型定义、内嵌Swagger Spec在内的所有代码。对应命令行选项
-generate=types,client,server,spec。

下面我们看看从宠物商店的OpenAPI Spec生成Go样板代码：

通过下面的命令生成样板代码：

 OpenAPI的 /components/schemas段中定义了可复用对象类型，oapi-codegen会生成对应的Go结构：

对于在handler中定义的inline类型，只会生成内联的、匿名的Go结构。这会导致重复的代码，应该避免。

对于paths中的每一个元素，都会生成一个Go Handler函数：

请求参数通过以下方式传递：

1. 大部分情况下，函数被编解码到echo.Context中
2. 路径变量作为Handler函数的参数
3. 其它请求头参数、查询参数、Cookie参数被存放在params变量中，例如：
   
   Go

   1 2 3 4 5

   // Parameters object for FindPets type FindPetsParams struct {    Tags  *[]string `json:"tags,omitempty"`    Limit *int32   `json:"limit,omitempty"`  // 可选参数，作为指针 }

使用命令行选项 -generate server可以为Echo生成Handlers注册函数： 

使用下面的代码注册Handlers到Echo服务器：

类似的，使用命令行选项 -generate chi-server可以生成Chi或net/http的Handlers注册函数。

OpenAPI默认隐含additionalProperties=true，也就是说请求中提供的任何没有明确定义的字段都应该被接受。由于在Go语言中处理这种动态属性需要大量样板代码，oapi-codegen默认假设additionalProperties=false，要改变此默认行为你需要修改OpenAPI Schema：

这样会生成如下结构：

使用命令行选项 -generate=client可以生成客户端代码：

每个OpenAPI Schema中定义的操作都对应了一个客户端函数。 

此工具专门用于从K8S模型类生成Open API模型（以Go结构的形式存放在GetOpenAPIDefinitions函数中）。

下载并安装：

要为指定的包生成模型，执行命令：

你的CRD通常会引用K8S核心库中的模型，因此需要同时为它们生成模型：

使用Operator Framework开发CRD的控制器时，你可以使用注释 +k8s:openapi-gen=true来生成Open API模型，生成的Schema示例如下：

下面的代码调用GetOpenAPIDefinitions函数，生成Swagger 2.0.0 API定义的JSON：

生成的Swagger API，仅仅包含模型信息，也就是definitions字段，但是不包含API端点（paths）。

如果需要生成API端点，则需要启动一个API Server并将需要生成API端点的模型注册进去：