openapi 3.0 规范说明

lxxxl0001

2795人浏览 · 2021-11-01 15:55:48

lxxxl0001 · 2021-11-01 15:55:48 发布

前言
任何项目在开发完成后都需要编写接口文档,而手动编写文档即消耗人力又可能由于维护不及时导致文档和项目版本不一致,反之如果使用swagger在项目更新的同时自动生成相应的接口文档则可以避免上述问题。由于swagger2.0的规范依赖于openapi 3.0版本的规范，所以在使用swagger生成文档前，了解和掌握openapi的规范是必要的,所以我下边列出了openapi文档的常用示例并赋予中文说明:

官方文档（中文版）
The OpenAPI Specification | 开放API规范

示例
openapi: “3.0.0”
info: //提供API相关的元数据
version: 1.0.0 //必选. API文档的版本信息(注意:这个版本和开放API 规范版本没有任何关系)。
title: Swagger Petstore //必选. 应用的名称。
description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification //对应用的简短描述。 CommonMark syntax 可以被用来表示富文本呈现。
termsOfService: http://swagger.io/terms/ //指向服务条款的URL地址，必须是URL地址格式。
contact: //所开放的API的联系人信息。
name: Swagger API Team
email: apiteam@swagger.io
url: http://swagger.io
license: //所开放的API的证书信息。
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers: //这是一个Server对象的数组，提供到服务器的连接信息。如果没有提供 servers 属性或者是一个空数组，那么默认为是url值为 /

url: http://petstore.swagger.io/api //必选. 指向目标主机的URL地址。
description: The production API server //一个可选的字符串，用来描述此URL地址
variables: //一组变量和值的映射，这些值被用来替换服务器URL地址内的模板参数。
username:
default: demo //必选. 当可替换的值没有被使用者指定时使用的默认值。
description: this value is assigned by the service provider //对服务器变量的可选的描述
port:
enum: //一组可枚举字符串值，当可替换选项只能设置为固定的某些值时使用。
- 8443
- 443
default: 8443
basePath:
default: v2
paths: //必选。对所提供的API有效的路径和操作。
/pets: //到各个端点的相对路径，路径必须以 / 打头，这个路径会被直接连接到 Server 对象的 url 字段以组成完整URL地址当做URL地址匹配时，不带路径参数的路径会被优先匹配。应该避免定义多个具有相同路径层级但是路径参数名不同的路径，因为他们是等价的。当匹配出现歧义时，由使用的工具自行决定使用那个路径。
$ref: ‘’ //指定对此路径的外部定义的引用
description: ‘’//可选描述字段
summary: ‘’ //可选描述包含的操作
get:
description: |
Returns all pets from the system that the user
operationId: findPets //用于标识此操作的唯一字符串，这个 id在此API内包含的所有操作中必须是唯一的。
tags: //用于控制API文档的标签列表，标签可以用于在逻辑上分组对资源的操作或作为其它用途的先决条件。
- test
parameters:
- name: tags //必选. 参数的名称。参数名是区分大小写。
in: query //必选. 参数的位置，可能的值有 “query”, “header”, “path” 或 “cookie”。
description: tags to filter by
required: false
style: form
schema:
type: array
items:
type: string
- name: limit
in: query
description: maximum number of results to return
required: false
schema:
type: integer
format: int32
responses:
‘200’:
description: pet response
content:
application/json:
schema:
type: array
items:
$ref: ‘#/components/schemas/Pet’
default:
description: unexpected error
content:
application/json:
schema:
$ref: ‘#/components/schemas/Error’
servers: //一个可用于此操作的额外的 server 数组，这里的定义会覆盖 Path Item 对象或顶层的定义。
- url:
callbacks: //回调内容和path item一致
{path}
post:
description: Creates a new pet in the store. Duplicates are allowed
operationId: addPet
requestBody:
description: Pet to add to the store
required: true
content:
application/json:
schema:
$ref: ‘#/components/schemas/NewPet’
responses:
‘200’:
description: pet response
content:
application/json:
schema:
$ref: ‘#/components/schemas/Pet’
default:
description: unexpected error
content:
application/json:
schema:
$ref: ‘#/components/schemas/Error’
/pets/{id}:
get:
description: Returns a user based on a single ID, if the user does not have access to the pet
operationId: find pet by id
parameters:
- name: id
in: path
description: ID of pet to fetch
required: true
schema:
type: integer
format: int64
responses:
‘200’:
description: pet response
content:
application/json:
schema:
$ref: ‘#/components/schemas/Pet’
default:
description: unexpected error
content:
application/json:
schema:
$ref: ‘#/components/schemas/Error’
delete:
description: deletes a single pet based on the ID supplied
operationId: deletePet
parameters:
- name: id
in: path
description: ID of pet to delete
required: true
schema:
type: integer
format: int64
responses:
‘204’:
description: pet deleted
default:
description: unexpected error
content:
application/json:
schema:
$ref: ‘#/components/schemas/Error’
components: //包含开放API规范固定的各种可重用组件。这里只提供schema示例，其余的（如header,response等）请自行查看openapi 3.0文档
schemas:
Pet:
oneOf:
- $ref: ‘#/components/schemas/PetV1’
- $ref: ‘#/components/schemas/PetV2’
discriminator: //如何区分不同的模式，来如何进行序列化和反序列化
propertyName: version //包含区分符值的属性的名称。
mapping:
1.0: ‘#/components/schemas/PetV1’
2.0: ‘#/components/schemas/PetV2’
PetV2:
allOf:
- $ref: ‘#/components/schemas/PetV1’
- type: object
required:
- id
properties:
id:
type: integer
format: int64

PetV1:
type: object
required:
- name
properties:
name:
type: string
tag:
type: string
address:
$ref: ‘#/components/schemas/Address’

Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
minimum: 100
maximum: 600
message:
type: string