openapi-yaml 语言规范简单翻译

最新推荐文章于 2023-11-15 15:07:41 发布

猿部族

最新推荐文章于 2023-11-15 15:07:41 发布

阅读量2.3k

点赞数 3

分类专栏： openapi

本文链接：https://blog.csdn.net/weixin_40326107/article/details/106016454

版权

openapi 专栏收录该内容

1 篇文章 0 订阅

订阅专栏

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: support@example.com
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": "support@example.com"   //联系人/组织的电子邮件地址
  },
  "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: support@example.com

对应的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 pets

json语法

"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:pets

json语法：

{
  "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: binary

multipart类型注意事项：

将请求体转移为操作时，一般使用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

猿部族

关注

3
点赞
踩
6

收藏

觉得还不错? 一键收藏
0
评论
openapi-yaml 语言规范简单翻译

1.对象描述1.1 固定字段 -- openapi string 必须参数定义openapi的规范版本号 -- info 信息对象必须参数提供有关api的元数据 -- servers 服务器对象数组用于提供目标服务器的连接信息如果不提供，默认将是一个有url的服务器对象 -- paths 路径对象必须的 api可用的操作路径 -- components 组件对象用于保存规范的各种模式的元素...
复制链接

扫一扫