YAML

YAML（Yet Another Markup Language）是一种数据序列化格式，通常被用来配置文件。它易于阅读，并且以数据结构为中心。YAML文件通常以`.yaml`或`.yml`为扩展名。

下面是一个YAML文件的简单示例：定义了一个人的基本信息，包括姓名、年龄、婚姻状态以及孩子的列表。

# 这是一个注释
name: John Doe
age: 30
married: true
children:- name: Jimmyage: 5- name: Jennyage: 7

OpenAPI

OpenAPI（之前称为Swagger）是一种规范，用于描述、消费和可视化 RESTful web 服务。它提供了一种可读性强且易于理解的格式，可以让人和机器都能读懂。OpenAPI 规范允许开发人员设计、构建、记录和使用 RESTful 服务，同时还提供了可视化界面，方便测试和交互。

OpenAPI 规范定义了几个核心组件，包括：

1. 概述（Info）：提供有关 API 的基本信息，例如标题、描述、版本、许可协议等。
2. 服务器（Servers）：定义 API 服务的地址和基础路径。
3. 路径（Paths）：描述 API 的端点（URL）和相关的请求方法（GET、POST、PUT 等）。
4. 操作（Operations）：定义每个端点的具体操作，包括请求和响应的详细信息。
5. 参数（Parameters）：描述请求参数，例如查询字符串、请求体等。
6. 响应（Responses）：定义可能的响应状态码以及相应的消息和格式。
7. 数据模型（Components）：提供可重用的数据模型，例如请求和响应的结构。

OpenAPI 规范可以采用 YAML 或 JSON 格式编写。YAML 格式更易于阅读和编写，而 JSON 格式则更适合机器解析。

OpenAPI 规范的一个优点是它可以让开发人员、API 用户和自动化工具轻松地理解和交互 API。这使得 API 的文档化、测试和集成变得更加简单。许多工具和库（如 Swagger UI、Postman、Springfox 等）都支持 OpenAPI 规范，可以自动生成 API 文档和可视化界面。

OpenAPI接口定义的YAML

OpenAPI规范允许以YAML格式定义接口的信息，包括端点、操作、参数、响应等。

一个简单的OpenAPI接口定义的YAML示例：定义了一个名为“Sample API”的API，该API有一个端点（/users）用于获取用户列表。定义了请求参数、响应以及用户的数据结构。

openapi: 3.0.0
info:version: 1.0.0title: Sample APIdescription: A sample API for demonstration purposes.termsOfService: https://example.com/termscontact:name: API Supportemail: support@example.comurl: https://example.com/supportlicense:name: Apache 2.0url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:- url: http://api.example.com/v1
paths:/users:get:tags:- Userssummary: Retrieve a list of users.description: Returns a list of registered users.parameters:- name: limitin: querydescription: The number of users to return.required: falseschema:type: integerminimum: 1maximum: 100responses:'200':description: A successful response.content:application/json:schema:type: arrayitems:$ref: '#/components/schemas/User''400':description: Bad request.'500':description: Internal server error.
components:schemas:User:type: objectrequired:- id- nameproperties:id:type: integerexample: 1name:type: stringexample: John Doeemail:type: stringexample:john.doe@example.com

Open API 的官方文档

Open API 的官方文档是由 OpenAPI Initiative（OAI）维护的。可以在 OpenAPI Initiative 的官方网站找到 Open API 的规范文档。这些文档详细介绍了 Open API 的各个方面，包括规范的核心组件、格式以及如何使用它来描述 RESTful 服务。

参考：

• OpenAPI 代码生成文档：GitHub - OpenAPITools/openapi-generator: OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
• OpenAPI 官方博客：https://www.openapis.org/blog

实现和工具

OpenAPI 还有一些流行的实现和工具，如 Swagger UI、Postman、Springfox 等，它们提供了 OpenAPI 规范的支持，并可以帮助开发者更轻松地创建、测试和文档化 API。这些工具和库通常也会附带相应的官方文档。