随着互联网行业的兴起，开发模式已逐步转换为微服务自治：小团队开发微服务，然后通过Restful接口相互调用。开发者们越来越渴望能够使用一种“官话”进行流畅的沟通，甚至实现多种编程语言系统的自动化交互。
开放API战略（Open API Initiativev）于2017年1月发表声明，2月发布实现草案，经过反复讨论， 标准API规范OAS（OpenAPI-Specification）3.0版本在2017年6月诞生。
OAS 3.0架构中将OpenAPI赋予了以下8个模块的定义，其中黄色模块为必选字段，绿色模块为可选字段：
各个主要模块工作流如下所示：
以下重点说明用户获取使OAS API信息的三个必选部分：
1.1 API基本信息用户查询获取OpenAPI的基本定义及信息，涉及以下两个模块内容：
l openapi
是否必选：必选
对象类型：String
类似于XML声明（<?xml version="1.0"?> ），用于设定文件应该使用哪一种规范进行解析。
l info
是否必选：必选
对象类型：Info Object
这个模块主要提供API的元数据。
以下为一个Info Object样例：
title: Sample Pet Store App #必须，应用名称
description: This is a sample server for apetstore. #应用的描述
termsOfService:
#应用的服务条款连接
contact: #应用提供商的联系方式
name: API Support
url:
email: support@example.com
license: #应用所遵循的协议
name: Apache 2.0
url:
version: 1.0.1 #应用版本
用户查询获取服务器的基本定义及信息，涉及以下模块信息：
servers
是否必选：必选
对象类型：[Server Object]
这个模块主要提供和目标服务器的连接信息，如果这个模块没有定义url，根据规范会自动生成一个url为/的Server Object。
例如：
servers:
- url: https://development.gigantic-server.com/v1 #必选，
description: Development server #非必选，url描述
查询API具体参数，涉及OAS剩余的模块，本文主要介绍paths和components模块。
l paths
是否必选：必选
对象类型：Paths Object
这个模块主要提供OpenAPI所在的目标服务器的连接信息，如果这个模块没有定义，根据规范会自动生成一个url为/的Server Object。通过多级定义，分别确定API的paths/method，并且通过$ref引用comonents模块中的定义，可以复用响应码等相关信息。对于携带body体的请求类型，requestBody可以提供example（或数组examples），这是非常灵活的（可以传入一个完整的例子，一个参考，甚至是一个URL的例子）。
例如：
/pets: #URL
get: #方法，get/post/..
description: Returns all pets .
#描述
responses: #响应模块
'200': #返回码为200，可以使用通配符定义响应
description: A list of pets. #响应描述
content: #Content字段
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/pet' #引用componets
l components
是否必选：非必选
对象类型：Components Object
这个模块主要提供每个OpenAPI自定义的字段定义，这部分定义的对象往往被paths中具体API进行引用：
− 响应 responses
− 参数 parameters
− 示例 examples
− 请求体 requestBodies
− 标题 headers
− 链接 links
− 回调 callbacks
− 模式 schemas
− 安全体系 securitySchemes
以下为一个Components Object样例：
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:
scopes:
write:pets: modify pets in
your account
read:pets: read your pets
2 如何使用OAS 设计可扩展的OpenAPI