OpenAPI 1

Submitted by Lizhe on Tue, 11/17/2020 - 02:15

OpenAPI ( OAS ) 是一个语言无关的 RESTful API 接口规范,

数据类型

OAS 使用几种已知的 format 格式来详细定义所使用的 type 数据类型。

20201117101817

OpenAPI的 根对象

# OpenAPI 规范版本号
openapi: 3.0.0

# API 元数据信息
info:

# 服务器连接信息
servers:

# API 的分组标签
tags: 

# 对所提供的 API 有效的路径和操作
paths:

# 一个包含多种纲要的元素,可重复使用组件
components:

# 声明 API 使用的安全机制
security:

# 附加文档
externalDocs:

 

Info 对象描述的是 元数据信息

# API 元数据信息
info:
  title:  xx开放平台接口文档                    # 应用的名称
  description: |                          
    简短的描述信息,支持 markdown 语法。 | 表示换行,< 表示忽略换行。
  version: "1.0.0"                            # API 文档的版本信息
  termsOfService: 'http://swagger.io/terms/'  # 指向服务条款的 URL 地址
  contact:                                    # 所开放的 API 的联系人信息
    name: API Support                           # 人或组织的名称
    url: http://www.example.com/support         # 指向联系人信息的 URL 地址
    email: apiteam@swagger.io                   # 人或组织的 email 地址
  license:                                    # 所开放的 API 的证书信息。
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

 

 

Server 表示一个服务器的对象。这里通常填写测试服务器或者生产服务器的 IP 地址、端口版本号等信息(指定基本 URL)。

# 服务器连接信息
servers:
  - url: https://development.gigantic-server.com/v1
    description: 开发服务器
  - url: https://staging.gigantic-server.com/v1
    description: 测试服务器
  - url: https://api.gigantic-server.com/v1
    description: 生产服务器

 

Tag 对象用于对 path 对象中的 API 进行分组,可以更美观的生成文档。

 

20201117111403

Components 对象

components 对象包含开放 API 规范规定的各种可重用组件。当没有被其他对象引用时,在这里定义的组件不会产生任何效果。

20201117123720

Path 对象

定义各个端点和操作的相对路径。

Pet 对象

20201117125651

 

参考 https://www.jianshu.com/p/5365ef83252a