YAML
YAML(Yet Another Markup Language)是一种数据序列化格式,通常被用来配置文件。它易于阅读,并且以数据结构为中心。YAML文件通常以`.yaml`或`.yml`为扩展名。
下面是一个YAML文件的简单示例:定义了一个人的基本信息,包括姓名、年龄、婚姻状态以及孩子的列表。
# 这是一个注释
name: John Doe
age: 30
married: true
children:
- name: Jimmy
age: 5
- name: Jenny
age: 7
OpenAPI
OpenAPI(之前称为Swagger)是一种规范,用于描述、消费和可视化 RESTful web 服务。它提供了一种可读性强且易于理解的格式,可以让人和机器都能读懂。OpenAPI 规范允许开发人员设计、构建、记录和使用 RESTful 服务,同时还提供了可视化界面,方便测试和交互。
OpenAPI 规范定义了几个核心组件,包括:
- 概述(Info):提供有关 API 的基本信息,例如标题、描述、版本、许可协议等。
- 服务器(Servers):定义 API 服务的地址和基础路径。
- 路径(Paths):描述 API 的端点(URL)和相关的请求方法(GET、POST、PUT 等)。
- 操作(Operations):定义每个端点的具体操作,包括请求和响应的详细信息。
- 参数(Parameters):描述请求参数,例如查询字符串、请求体等。
- 响应(Responses):定义可能的响应状态码以及相应的消息和格式。
- 数据模型(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.0
title: Sample API
description: A sample API for demonstration purposes.
termsOfService: https://example.com/terms
contact:
name: API Support
email: [email protected]
url: https://example.com/support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: http://api.example.com/v1
paths:
/users:
get:
tags:
- Users
summary: Retrieve a list of users.
description: Returns a list of registered users.
parameters:
- name: limit
in: query
description: The number of users to return.
required: false
schema:
type: integer
minimum: 1
maximum: 100
responses:
'200':
description: A successful response.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'400':
description: Bad request.
'500':
description: Internal server error.
components:
schemas:
User:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 1
name:
type: string
example: John Doe
email:
type: string
example:[email protected]
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。这些工具和库通常也会附带相应的官方文档。