openapi-yaml 语言规范简单翻译
目录
1.对象描述
1.1 固定字段
1.1.1 信息对象（info）
1.1.2 服务器对象(servers)
1.1.3 组件对象（components）
1.1.4 paths对象介绍
1.1.5 path项对象
1.1.6 path项对象-操作对象描述（Operation Object）
1.1.7 path项对象-外部文档对象 External Documentation Object
1.1.8 path项对象-参数对象 parameters Object
1.1.8 path项对象-请求参数对象 Request body Object
1.1.9 path项对象-响应对象 Responses Object
1.对象描述
1.1 固定字段
-- openapi string 必须参数 定义openapi的规范版本号
-- info 信息对象 必须参数 提供有关api的元数据
-- servers 服务器对象数组 用于提供目标服务器的连接信息 如果不提供，默认将是一个有url的服务器对象
-- paths 路径对象 必须的 api可用的操作路径
-- components 组件对象 用于保存规范的各种模式的元素
-- security 安全需求对象数组
-- tags 标签对象数组
-- externalDocs 外部文档对象
1.1.1 信息对象（info）
-- titile string 必须 应用程序的名称
-- description string 应用程序简单描述
-- termsOfService string api服务条款网址
-- contact Contact Object 公开api来呢西信息
-- license License Object 公开api许可信息
-- version string 必须的 OpenAPI文档版本
info实例
yaml描述：
title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
name: API Support
url: http://www.example.com/support
email: [email protected]
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
对应的json描述
{
"title": "Sample Pet Store App",
"description": "This is a sample server for a pet store.",
"termsOfService": "http://example.com/terms/",
"contact": {
"name": "API Support", //联系人或者组织的标识名称
"url": "http://www.example.com/support", //指向联系人的url
"email": "[email protected]" //联系人/组织的电子邮件地址
},
"license": {
"name": "Apache 2.0", //必须的 api的许可证名称
"url": "http://www.apache.org/licenses/LICENSE-2.0.html" //api许可证的url地址
},
"version": "1.0.1"
}1.1.2 服务器对象(servers)
-- url string 必须的 目标主机的url
-- description string 主机简单描述
-- variables Map[string, server Variable Obejct] 变量名称和值之间的映射，此处值是用于替换服务器的url模板
单个服务描述为：
yaml描述：
name: API Support
url: http://www.example.com/support
email: [email protected]
对应的json描述
{
“ url ”：“ https://development.gigantic-server.com/v1 ”，
“ description ”：“开发服务器”
}多个服务描述方式
yaml描述：
servers:
- url: https://development.gigantic-server.com/v1
description: Development server
- url: https://staging.gigantic-server.com/v1
description: Staging server
- url: https://api.gigantic-server.com/v1
description: Production server
josn描述：
{
"servers": [
{
"url": "https://development.gigantic-server.com/v1",
"description": "Development server"
},
{
"url": "https://staging.gigantic-server.com/v1",
"description": "Staging server"
},
{
"url": "https://api.gigantic-server.com/v1",
"description": "Production server"
}
]
}下面展示如何将变量用于服务器配置
yaml描述：
servers:
- url: https://{username}.gigantic-server.com:{port}/{basePath}
description: The production API server
variables:
username:
# note! no enum here means it is an open value
default: demo
description: this value is assigned by the service provider, in this example `gigantic-server.com`
port:
enum:
- '8443'
- '443'
default: '8443'
basePath:
# open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
default: v2
json描述：
{
"servers": [
{
"url": "https://{username}.gigantic-server.com:{port}/{basePath}",
"description": "The production API server",
"variables": {
"username": {
"default": "demo",
"description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
},
"port": {
"enum": [
"8443",
"443"
],
"default": "8443"
},
"basePath": {
"default": "v2"
}
}
}
]
}服务器变量对象
-- enum string数组 如果替换的选项为有限集合，则使用字符串的枚举
-- default string 必须的 如果没有提供代替值，就使用默认
-- description 变量描述
1.1.3 组件对象（components）
-- schemas 可重用的架构对象
-- responses 可重用的响应对象
-- parameters 可重用的参数对象
-- examples 可重用的实例对象
-- requestBodies 可重用的请i去主体对象
-- headers 可宠用的请求头对象
-- securitySchemes 可重用的安全方案对象
-- links 可重用的链接对象
-- callbacks 可重用的回调对象
组件对象实例
yaml语法
components:
schemas:
Category:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
Tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
parameters:
skipParam:
name: skip
in: query
description: number of items to skip
required: true
schema:
type: integer
format: int32
limitParam:
name: limit
in: query
description: max records to return
required: true
schema:
type: integer
format: int32
responses:
NotFound:
description: Entity not found.
IllegalInput:
description: Illegal input for operation.
GeneralError:
description: General Error
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralError'
securitySchemes:
api_key:
type: apiKey
name: api_key
in: header
petstore_auth:
type: oauth2
flows:
implicit:
authorizationUrl: http://example.org/api/oauth/dialog
scopes:
write:pets: modify pets in your account
read:pets: read your petsjson语法
"components": {
"schemas": {
"Category": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
},
"Tag": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
}
},
"parameters": {
"skipParam": {
"name": "skip",
"in": "query",
"description": "number of items to skip",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
"limitParam": {
"name": "limit",
"in": "query",
"description": "max records to return",
"required": true,
"schema" : {
"type": "integer",
"format": "int32"
}
}
},
"responses": {
"NotFound": {
"description": "Entity not found."
},
"IllegalInput": {
"description": "Illegal input for operation."
},
"GeneralError": {
"description": "General Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GeneralError"
}
}
}
}
},
"securitySchemes": {
"api_key": {
"type": "apiKey",
"name": "api_key",
"in": "header"
},
"petstore_auth": {
"type": "oauth2",
"flows": {
"implicit": {
"authorizationUrl": "http://example.org/api/oauth/dialog",
"scopes": {
"write:pets": "modify pets in your account",
"read:pets": "read your pets"
}
}
}
}
}
}1.1.4 paths对象介绍
-- /{path} path项对象 到单个短线的相对路径，字段名称必须以/开头，路径会自动追加到url后面，用以构造完成的url
path对象实例
yaml语法：
/pets:
get:
description: Returns all pets from the system that the user has access to
responses:
'200':
description: A list of pets.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/pet'
json语法：
{
"/pets": {
"get": {
"description": "Returns all pets from the system that the user has access to",
"responses": {
"200": {
"description": "A list of pets.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/pet"
}
}
}
}
}
}
}
}
}1.1.5 path项对象
-- $ref string 允许对此路径项进行外部定义，被引用的格式必须采用路径项对象
-- summary string 可选的字段摘要，旨在应用于此路径中的所有操作
-- description string 可选字段 应用于此路径中的所有操作
-- get 操作对象 此路径上的get操作的定义
-- put 操作对象 此路径上的put操作的定义
-- post 操作对象 此路径上的post操作的定义
-- delete 操作对象 此路径上的delete操作的定义
-- options 操作对象 此路径上的options操作的定义
-- head 操作对象 此路径上的head操作的定义
-- patch 操作对象 此路径上的patch操作的定义
-- trace 操作对象 此路径上的trace操作的定义
-- servers 服务对象 用于服务此路径中所有操作的备用数组
-- parameters 参数对象 适用于此路径下描述的所有操作的参数列表
path项对象实例
yaml语法：
get:
description: Returns pets based on ID
summary: Find pets by ID
operationId: getPetsById
responses:
'200':
description: pet response
content:
'*/*' :
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
default:
description: error payload
content:
'text/html':
schema:
$ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
in: path
description: ID of pet to use
required: true
schema:
type: array
style: simple
items:
type: string json语法：
{
"get": {
"description": "Returns pets based on ID",
"summary": "Find pets by ID",
"operationId": "getPetsById",
"responses": {
"200": {
"description": "pet response",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
},
"default": {
"description": "error payload",
"content": {
"text/html": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of pet to use",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "simple"
}
]
}1.1.6 path项对象-操作对象描述（Operation Object）
-- tags string数组 api文档控制标签列表 标签可以用于按照资源或任何其他限定符对操作进行逻辑分组
-- summary string 此操作摘要
-- description string 此操作详细描述
-- externalDocs 外部文档对象 有关此操作的其他外部文档
-- opreationId string 用于标识操作的唯一字符串 该id描述的所有操作中必须唯一 工具和库可以根据operationId唯一的标识一个操作，因此建议尊村通用的编码命名规则
-- parameters parameter Object 参数列表，如果在Path Item上已经定义了参数，则新定义的参数会覆盖他，但永远不能删除他，该列表不能包含重复的参数，唯一参数又名称和位置组合定义
-- requestBody Request Body Obecjt 请求正文
-- response Response Body 必须的 定义此操作返回的可能相应列表
-- callbacks Map[Callback Object] 回调函数对象
-- deprecated boolean 宣布不推荐使用的操作
-- security SecurityReqyirement数组 声明可以用于此操作的安全机制
-- servers server Obejct数组 服务此操作的备用数组
操作对象实例
yaml语法：
tags:
- pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
- name: petId
in: path
description: ID of pet that needs to be updated
required: true
schema:
type: string
requestBody:
content:
'application/x-www-form-urlencoded':
schema:
properties:
name:
description: Updated name of the pet
type: string
status:
description: Updated status of the pet
type: string
required:
- status
responses:
'200':
description: Pet updated.
content:
'application/json': {}
'application/xml': {}
'405':
description: Invalid input
content:
'application/json': {}
'application/xml': {}
security:
- petstore_auth:
- write:pets
- read:petsjson语法：
{
"tags": [
"pet"
],
"summary": "Updates a pet in the store with form data",
"operationId": "updatePetWithForm",
"parameters": [
{
"name": "petId",
"in": "path",
"description": "ID of pet that needs to be updated",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"name": {
"description": "Updated name of the pet",
"type": "string"
},
"status": {
"description": "Updated status of the pet",
"type": "string"
}
},
"required": ["status"]
}
}
}
},
"responses": {
"200": {
"description": "Pet updated.",
"content": {
"application/json": {},
"application/xml": {}
}
},
"405": {
"description": "Invalid input",
"content": {
"application/json": {},
"application/xml": {}
}
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
]
}1.1.7 path项对象-外部文档对象 External Documentation Object
-- description string 简单的对象描述
-- url string 必须的 目标文档路径
yaml语法：
description: Find more info here
url: https://example.com
json语法：
{
"description": "Find more info here",
"url": "https://example.com"
}1.1.8 path项对象-参数对象 parameters Object
描述单个操作的参数，唯一参数又参数名称和位置组合定义
参数位置 in 定义了四个可能的参数位置：
path：与path Templating一起使用
query：附加到url的查询参数 例如：/item?id=***,查询参数为id
header：自定义请求头，作为请求的一部分
cookie：用于将特定的cookie值传递给指定的api
-- name sting 必须的 区分大小写
a.如果in是"path",则该name字段务必对应于Path Object中路径字段的关联路径
b.如果in是"header"，并且name字段是"Accept","Content-Type","Authorization",那么参数的定义应该被忽略
-- in string 参数的位置，可能的字段为："query","header","path","cookie"
-- description string 参数的简要说明
-- required boolean 是否是必填参数，如果in是"path",那么此属性是必须填的，其值必须为true，否则，可以包含该属性，默认值为false
-- deprecated boolean 不推荐使用参数指定
-- allowEmptyValue boolean 参数 设置传递空值参数的能力，仅对query参数有效，并允许发送带有控制的参数，默认值为false，如果使用style，并且无法序列化，此参数值将被忽略
以下两种方式用来指定参数序列化规则-schema和style
-- style string 根据参数值类型序列化参数值 默认值(基于in的值)：query-from;path-simple;header-simple,cookie-from
-- explode boolean true:Obejct类型和Array类型的参数，将此两种类型中的参数映射为用map中key-value形式表示的单独参数或者数组,对于其他类型的参数，则此属性无效，当style为from时，默认值是true，其他值则为false
-- allowReserved boolean 确定参数值是否应允许包含由RFC3986 定义的保留字符，:/?#[]@!$&'()*+,;=而不进行百分比编码。此属性仅适用于in值为的参数query。默认值为false。
-- schema Schema Object 用于定义参数使用类型
-- example Any 后面补充
-- examples Map[Example Object] 后面补充
样式值 Style values 这里不做过多介绍，有兴趣的朋友可以去查看官网文档
参数对象实例
具有64位整数数组的表头参数(header parameters)
yaml语法：
name: token
in: header
description: token to be passed as a header
required: true
schema:
type: array
items:
type: integer
format: int64
style: simple
json语法：
{
"name": "token",
"in": "header",
"description": "token to be passed as a header",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"style": "simple"
}string 类型的路径参数（path parameters）
yaml语法：
name: username
in: path
description: username to fetch
required: true
schema:
type: string
json语法：
{
"name": "username",
"in": "path",
"description": "username to fetch",
"required": true,
"schema": {
"type": "string"
}
}一个string类型的可选查询参数，查询参数中允许多个重复的值
yaml语法：
name: id
in: query
description: ID of the object to fetch
required: false
schema:
type: array
items:
type: string
style: form
explode: true
json语法：
{
"name": "id",
"in": "query",
"description": "ID of the object to fetch",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true
}一个自由查询参数，一个允许参数未定义(undefined)的特殊类型
yaml语法：
in: query
name: freeForm
schema:
type: object
additionalProperties:
type: integer
style: form
json语法：
{
"in": "query",
"name": "freeForm",
"schema": {
"type": "object",
"additionalProperties": {
"type": "integer"
},
},
"style": "form"
}使用content定义的复杂参数，用来定义序列化
yaml语法：
in: query
name: coordinates
content:
application/json:
schema:
type: object
required:
- lat
- long
properties:
lat:
type: number
long:
type: number
json语法：
{
"in": "query",
"name": "coordinates",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"lat",
"long"
],
"properties": {
"lat": {
"type": "number"
},
"long": {
"type": "number"
}
}
}
}
}
}1.1.8 path项对象-请求参数对象 Request body Object
-- description string 请求正文的简单描述
-- content Map[string,Media Type Object] 必须的，请求正文的内容，媒体类型或者媒体类型范围的数组
-- requred boolean 确认请求中是否需要请求主体
请求体实例
yaml语法：
description: user to add to the system
content:
'application/json':
schema:
$ref: '#/components/schemas/User'
examples:
user:
summary: User Example
externalValue: 'http://foo.bar/examples/user-example.json'
'application/xml':
schema:
$ref: '#/components/schemas/User'
examples:
user:
summary: User Example in XML
externalValue: 'http://foo.bar/examples/user-example.xml'
'text/plain':
examples:
user:
summary: User example in text plain format
externalValue: 'http://foo.bar/examples/user-example.txt'
'*/*':
examples:
user:
summary: User example in other format
externalValue: 'http://foo.bar/examples/user-example.whatever'
json语法：
{
"description": "user to add to the system",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/User"
},
"examples": {
"user" : {
"summary": "User Example",
"externalValue": "http://foo.bar/examples/user-example.json"
}
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/User"
},
"examples": {
"user" : {
"summary": "User example in XML",
"externalValue": "http://foo.bar/examples/user-example.xml"
}
}
},
"text/plain": {
"examples": {
"user" : {
"summary": "User example in Plain text",
"externalValue": "http://foo.bar/examples/user-example.txt"
}
}
},
"*/*": {
"examples": {
"user" : {
"summary": "User example in other format",
"externalValue": "http://foo.bar/examples/user-example.whatever"
}
}
}
}
}字符串数组类型的请求主体参数
yaml语法：
description: user to add to the system
required: true
content:
text/plain:
schema:
type: array
items:
type: string
josn语法：
{
"description": "user to add to the system",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}媒体类型对象 Media Type Object
-- schema Schema Object 定义请求类型模式
-- example Any 媒体类型，对象应该采用给媒体类型指定的正确格式，example与examples互斥
-- examples Map[string,Example Object] 媒体类型，对象应该采用给媒体类型指定的正确格式，example与examples互斥
-- encoding Map[string,Encoding Object] 属性名称和编码信息之间的映射，key为属性名称（必须作为schema中的一个属性存在），当media type 为"multipart"或者"application、x-www-from-urlencoded"时，只允许在request Body Object中使用
媒体对象实例
yaml语法：
application/json:
schema:
$ref: "#/components/schemas/Pet"
examples:
cat:
summary: An example of a cat
value:
name: Fluffy
petType: Cat
color: White
gender: male
breed: Persian
dog:
summary: An example of a dog with a cat's name
value:
name: Puma
petType: Dog
color: Black
gender: Female
breed: Mixed
frog:
$ref: "#/components/examples/frog-example"
json语法：
{
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
},
"examples": {
"cat" : {
"summary": "An example of a cat",
"value":
{
"name": "Fluffy",
"petType": "Cat",
"color": "White",
"gender": "male",
"breed": "Persian"
}
},
"dog": {
"summary": "An example of a dog with a cat's name",
"value" : {
"name": "Puma",
"petType": "Dog",
"color": "Black",
"gender": "Female",
"breed": "Mixed"
},
"frog": {
"$ref": "#/components/examples/frog-example"
}
}
}
}
}文件上传注意内容：
# 使用base64编码传输文件
schema:
type: string
format: base64
# 使用二进制编码传输文件（流）
schema:
type: string
format: binary在post请求中提交一个文件的请求体，大致是下面这样的写法：
requestBody:
content:
application/octet-stream:
# any media type is accepted, functionally equivalent to `*/*`
schema:
# a binary file of any type
type: string
format: binary另外，可以指定特定的媒体类型
# multiple, specific media types may be specified:
requestBody:
content:
# a binary file of type png or jpeg
'image/jpeg':
schema:
type: string
format: binary
'image/png':
schema:
type: string
format: binary 上传多个文件时，媒体类型multipart是必须被使用到的
requestBody:
content:
multipart/form-data:
schema:
properties:
# The property name 'file' will be used for all files.
file:
type: array
items:
type: string
format: binarymultipart类型注意事项：
将请求体转移为操作时，一般使用multipart/form-data作为Content-Type。与2.0相比，在使用multipart content时，schema 必须为操作定义输入参数。这支持复杂结构以及多个文件上传机制
传入multipart类型时，可以使用边界来分隔要传输的内容的各个部分，因此，为以下内容Content-Type定义了以下默认值multipart：
a.如果属性是原始值或原始值数组，则默认的Content-Type为 text/plain
b.如果属性是复杂的或复杂值的数组，则默认的Content-Type为 application/json
c.如果属性是type: string+format: binary或string+format: base64（又名文件对象），则默认的Content-Type为application/octet-stream
例如：
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
id:
type: string
format: uuid
address:
# default Content-Type for objects is `application/json`
type: object
properties: {}
profileImage:
# default Content-Type for string/binary is `application/octet-stream`
type: string
format: binary
children:
# default Content-Type for arrays is based on the `inner` type (text/plain here)
type: array
items:
type: string
addresses:
# default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
type: array
items:
type: '#/components/schemas/Address'1.1.9 path项对象-响应对象 Responses Object
操作响应容器，容器会将http请求响应结果映射到预期写好的响应中
default创建默认的响应，处理事前未能考虑到的返回
-- status code Response Object 响应状态码，对应的是一个响应对象
响应对象 Response Object
-- description string 必须的 简单的描述
-- headers Map[string, Header Object | Reference Object] 将
-- content Map[string, Media Type Object]
-- links Map[string, Link Object | Reference Object]
实例
返回值是复杂数组时：
yaml语法：
description: A complex object array response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VeryComplexType'
json语法：
{
"description": "A complex object array response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VeryComplexType"
}
}
}
}
}
返回值是string类型时
yaml语法：
description: A simple string response
representations:
text/plain:
schema:
type: string
json语法：
{
"description": "A simple string response",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}带标题的纯文本响应
yaml语法：
description: A simple string response
content:
text/plain:
schema:
type: string
example: 'whoa!'
headers:
X-Rate-Limit-Limit:
description: The number of allowed requests in the current period
schema:
type: integer
X-Rate-Limit-Remaining:
description: The number of remaining requests in the current period
schema:
type: integer
X-Rate-Limit-Reset:
description: The number of seconds left in the current period
schema:
type: integer
json语法：
{
"description": "A simple string response",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
},
"headers": {
"X-Rate-Limit-Limit": {
"description": "The number of allowed requests in the current period",
"schema": {
"type": "integer"
}
},
"X-Rate-Limit-Remaining": {
"description": "The number of remaining requests in the current period",
"schema": {
"type": "integer"
}
},
"X-Rate-Limit-Reset": {
"description": "The number of seconds left in the current period",
"schema": {
"type": "integer"
}
}
}
}无返回值的响应：
yaml语法：
description: object created
json语法：
{
"description": "object created"
}
1.1.8 path项对象-参数对象 parameters Object
1.1.8 path项对象-参数对象 parameters Object
1.1.8 path项对象-参数对象 parameters Object
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--