目录
文章目录
OpenAPI Specification
Swagger Specification 是一种 API Specification（API 规范），2015 年，SmartBear Software 将 Swagger Specification 捐赠给 Linux Foundation，并改称为 OpenAPI Specification，简称（OAS）。SmartBearSoftware 也作为 OpenAPI Initiative（OAI）的创始成员，该机构以开放和透明的方式管理 OAS 的发展。
OpenAPI Specification 本质上是一种 RESTful API 的 API Description Format（描述格式），允许用户用于描述整个 API。OpenAPI 规范可以用 YAML 或 JSON 编写，包括：
- 每个 API 的可用端点（e.g. /users）和操作（e.g. GET /users，POST /users）。
- 操作参数每个操作的输入和输出。
- 认证方式。
- 联系信息，许可证，使用条款和其他信息。
通常的，我们可以根据需要手动的编写一个 OpenAPI Specification 或者让它从源代码中的注释自动生成。
Swagger 生态组件Swagger 是基于 OpenAPI Specification 的一系列生态组件：
- Swagger Hub：基于 OpenAPI Specification 的设计和文档平台。
- Swagger Inspector：基于 OpenAPI Specification 的测试平台。
- Swagger Editor：基于浏览器的编辑器，我们可以使用它来编写我们 OpenAPI 规范。
- Swagger Codegen：基于 OpenAPI Specification 的（服务端或客户端）代码生成工具。
- Swagger UI：将我们编写的 OpenAPI 规范呈现为交互式的 API 文档。
- ReDoc：一款优雅的 OpenAPI Specification UI 平台。
基本概念
OpenAPI Root Object（根对象）
OpenAPI 数据类型
定义一个请求 API
一个请求 API 主要由 Endpoint、Parameters、Body 等部分组成，我们需要分别定义。
- 官方示例：https://editor.swagger.io/
定义元信息（Metadata）
title: 这是标题（必填）。
description: 这里是一段描述。
termsOfService: API 可以测试地址。
contact:
name: 联系人。
url: 联系人地址。
email: 联系人邮箱。
license:
name: Apache 2.0 授权信息
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: OpenAPI 版本号（必填）
定义请求 Endpoint
/pets: # API 请求路径，如果需要 path value 可以使用 /pets/{petId}。
get: # get 请求，同理还有 put，post，delete，options 等方法。
description: 这是一段描述信息。
responses: # 响应部分定义。
'200': # 响应码。
description: 又是一段描述 。
content: # 内容。
application/json: # context-type。
schema:
type: array # 类型。
items: # array 字段所包含的元素。
$ref: '#/components/schemas/pet' # 引用组件，每个元素是一个组件，下文详细说明。
定义请求 Parameters
- 在 Header 中添加参数。
name: token
in: header # 这里是固定值。
description: token to be passed as a header # 描述信息。
required: true # 是否必需的。
schema:
type: array # 类型。
items:
type: integer
format: int64
- 在 Path 中添加参数。
name: username
in: path # 这里是固定值。
description: username to fetch
required: true
schema:
type: string
- 在 Query 中添加参数。
name: id
in: query # 这里是固定值。
description: ID of the object to fetch
required: false
schema:
type: array
items:
type: string
style: form
explode: true
定义请求 Body
这里使用 requestBody 作为请求体。
description: user to add to the system # 描述信息。
content: # 定义请求体。
'application/json': # context-type
schema: # 请求的格式。
$ref: '#/components/schemas/User' # 组件。
examples: # 例子。
user:
summary: User Example
externalValue: 'http://foo.bar/examples/user-example.json'
'application/xml': # context-type
schema:
$ref: '#/components/schemas/User'
examples:
user:
summary: User Example in XML
externalValue: 'http://foo.bar/examples/user-example.xml'
'text/plain': # context-type
examples:
user:
summary: User example in text plain format
externalValue: 'http://foo.bar/examples/user-example.txt'
'*/*':
examples: # context-type
user:
summary: User example in other format
externalValue: 'http://foo.bar/examples/user-example.whatever'
定义可复用组件
当我们使用 curl 此类的工具调用 API 时，通常会使用 JSON 格式类编写 Request Body。为了让 Request Body 具有一定的可重用性，所以 OpenAPI 引入了 Components（组件）的概念。简而言之，就是可重用的 Schema。
components:
schemas:
ErrorModel:
type: object
required:
- message
- code
properties:
message:
type: string
code:
type: integer
minimum: 100
maximum: 600
ExtendedErrorModel:
allOf:
- $ref: '#/components/schemas/ErrorModel'
- type: object
required:
- rootCause
properties:
rootCause:
type: string
# OpenAPI的版本，可用版本 3.0.0, 3.0.1, 3.0.2
openapi: 3.0.0
info:
title: '标题'
description: '描述'
version: '此OAS的版本，示例0.1.9'
# 提供此 API 的服务器地址列表
servers:
- url: http://api.example.com/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging-api.example.com
description: Optional server description, e.g. Internal staging server for testing
# API 端点列表
paths:
# 端点 /users
/users:
# 端点 /users 的 GET 方法
get:
# 描述性信息
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
# 响应规格说明
responses:
# 200响应说明
'200': # status code
description: A JSON array of user names
# 200 响应是 JSON 格式
content:
application/json:
# JSON 的 Schema
schema:
# 数组类型
type: array
items:
type: string
# 端点 /users 的 POST 方法
post:
summary: Creates a user.
# 请求体
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
responses:
'201':
description: Created
# 端点 /user/{userId} 的 POST 方法
# {} 中的是路径变量
/user/{userId}:
get:
summary: Returns a user by ID.
# 参数说明
parameters:
- name: userId
# 这是一个路径变量
in: path
required: true
description: The ID of the user to return.
# Schema 中可以包含字段的验证规则
schema:
type: integer
format: int64
minimum: 1
responses:
'200':
description: A user object.
content:
application/json:
schema:
# 对象类型
type: object
# 包含属性声明
properties:
id:
type: integer
format: int64
example: 4
name:
type: string
example: Jessica Smith
# 异常处理
'400':
description: The specified user ID is invalid (not a number).
'404':
description: A user with the specified ID was not found.
default:
description: Unexpected error
https://help.coding.net/docs/management/api/import/openapi.html
https://www.breakyizhan.com/swagger/2806.html
