OpenAPI规范摘要
介绍
OpenAPI 规范（OAS）定义了⼀个标准的、语⾔⽆关的 RESTful API 接⼝规范，它可以同时允许开发⼈员和操作系统查看并理解某个服务的功能，⽽⽆需访问源代码，⽂档或⽹络流量检查（既⽅便⼈类学习和阅读，也⽅便机器阅读）。正确定义 OAS 后，开发者可以使⽤最少的实现逻辑来理解远程服务并与之交互。
此外，⽂档⽣成⼯具可以使⽤ OpenAPI 规范来⽣成 API ⽂档，代码⽣成⼯具可以⽣成各种编程语⾔下的服务端和客户端代码，测试代码和其他⽤例。
数据类型
OAS 使⽤⼏种已知的format格式来详细定义所使⽤的type数据类型。
format属性是开放的字符串值，可以是⾃定义的任意类型值，⽐如：email、uuid。
OAS 定义的formats类型如下：
通⽤名称数据类型数据格式描述
integer integer int32signed 32 bits，32位有符号数
long integer int64signed 64 bits，64位有符号数
float number float
double number double
string string
byte string byte base64 encoded characters，base64 编码字符
binary string binary any sequence of octets
boolean boolean
date string date参考 - full-date
dateTime string date-time参考 - date-time
password string password UI 提⽰隐藏输⼊
OpenAPI 根对象
这是 OpenAPI 的根⽂档对象。
# OpenAPI 规范版本号
openapi: 3.0.0
# API 元数据信息
info:
# 服务器连接信息
servers:
# API 的分组标签
tags:
# 对所提供的 API 有效的路径和操作
paths:
# ⼀个包含多种纲要的元素，可重复使⽤组件
components:
# 声明 API 使⽤的安全机制
security:
# 附加⽂档
externalDocs:
Info 对象
Info 对象描述 API 的元数据信息。
# API 元数据信息
title:  xx开放平台接⼝⽂档                    # 应⽤的名称
description: |
简短的描述信息，⽀持 markdown 语法。 | 表⽰换⾏，< 表⽰忽略换⾏。
version: "1.0.0"                            # API ⽂档的版本信息
termsOfService: 'swagger.io/terms/'  # 指向服务条款的 URL 地址
contact:                                    # 所开放的 API 的联系⼈信息
name: API Support                          # ⼈或组织的名称
url: ample/support        # 指向联系⼈信息的 URL 地址
email: apiteam@swagger.io                  # ⼈或组织的 email 地址
license:                                    # 所开放的 API 的证书信息。
name: Apache 2.0
url: '/licenses/LICENSE-2.0.html'
Server 对象
ample/v1/users?role=admin&status=active
\ __________________ / \__/ \ ______________________ /
服务器URL      端点路径查询参数
Server 表⽰⼀个服务器的对象。这⾥通常填写测试服务器或者⽣产服务器的 IP 地址、端⼝版本号等信息（指定基本 URL）。
# 服务器连接信息
servers:
- url: development.gigantic-server/v1
description: 开发服务器
- url: staging.gigantic-server/v1
description: 测试服务器
- url: api.gigantic-server/v1
description: ⽣产服务器
Tag 对象
Tag 对象⽤于对 path 对象中的 API 进⾏分组，可以更美观的⽣成⽂档。
# API 的分组标签
tags:
-
name: pet
description: 与宠物相关的接⼝
externalDocs:
description: 外部⽂档
url: 'swagger.io'
- name: store
description: 宠物商店
- name: user
description: ⽤户操作相关
externalDocs:
description: 外部⽂档
url: 'swagger.io'
External Documentation 对象
允许引⽤外部资源来扩展⽂档。
# 附加⽂档
externalDocs:
description: Find out more about Swagger
url: 'swagger.io'
Components 对象
components对象包含开放 API 规范规定的各种可重⽤组件。当没有被其他对象引⽤时，在这⾥定义的组件不会产⽣任何效果。
# ⼀个包含多种纲要的元素，可重复使⽤组件
components:
schemas:
responses:
parameters:
examples:
requestBodies:
headers:
securitySchemes:
links:
callbacks:
Path 对象
定义各个端点和操作的相对路径。
# 对所提供的 API 有效的路径和操作
paths:
/pet/{petId}:
get:
tags:
- pet
summary: 简要总结，描述此路径内包含的所有操作。
description: 详细说明，⽤于描述此路径包含的所有操作。      operationId: getPetById      # 此操作的唯⼀标识符
parameters:                # 参数列表
- name: petId
in: path
description: 路径参数，宠物 ID。
required: true
schema:
type: integer
format: int64
responses:                  # 接⼝响应内容
'200':
description: 操作成功
content:
application/json:
schema:
type: object
properties:
id:
type: integer
format: int64
category:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
name:
type: string
example: doggie
photoUrls:
type: array
items:
type: string
tags:
type: array
items:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
status:
type: string
description: 宠物在商店的状态
enum:
- available
- pending
- sold
'400':
description: ⽆效的 id
'404':
description: 不到指定的资源
security:            # 作⽤于此操作的安全机制
- api_key: []        # 可以声明⼀个空数组来变相的移除顶层的安全声明返回的 Pet 对象详解：
返回的 Pet 对象详解
使⽤components对象进⾏优化：
# 对所提供的 API 有效的路径和操作
paths:
'/pet/{petId}':
get:
tags:
- pet
summary: 简要总结，描述此路径内包含的所有操作
description: 详细说明，⽤于描述此路径包含的所有操作
operationId: getPetById      # 此操作的唯⼀标识符
parameters:                  # 参数列表
- name: petId
in: path
description: pet ID
required: true
schema:
type: integer
format: int64
responses:                  # 响应列表
'200':
description: 操作成功
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
'400':
description: ⽆效的 id
'404':
description: 不到指定的资源
security:            # 作⽤于此操作的安全机制
- api_key: []        # 可以声明⼀个空数组来变相的移除顶层的安全声明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
Pet:
type: object
properties:
id:
type: integer
format: int64
category:
$ref: '#/components/schemas/Category'
name:restful接口详解
type: string
example: doggie
photoUrls:
type: array
items:
type: string
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
status:
type: string
description: 宠物在商店的状态
enum:
- available
- pending
-
sold
通过components对象封装可重⽤对象，然后通过$ref标签进⾏引⽤：

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。