基于OAS设计可扩展OpenAPI的示例分析
这篇文章的内容主要围绕基于OAS设计可扩展OpenAPI的示例分析进行讲述，文章内容清晰易懂，条理清晰，非常适合新手学习，值得大家去阅读。感兴趣的朋友可以跟随小编一起阅读吧。希望大家通过这篇文章有所收获！
目前创新互联已为近1000家的企业提供了网站建设、域名、虚拟空间、网站改版维护、企业网站设计、苍南网站维护等服务，公司将坚持客户导向、应用为本的策略，正道将秉承"和谐、参与、激情"的文化，与客户和合作伙伴齐心协力一起成长，共同发展。
随着互联网行业的兴起，开发模式已逐步转换为微服务自治：小团队开发微服务，然后通过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声明（ ），用于设定文件应该使用哪一种规范进行解析。
l info
是否必选：必选
对象类型：Info Object
这个模块主要提供API的元数据。
以下为一个Info Object样例：
title: Sample Pet Store App #必须，应用名称
description: This is a sample server for apetstore. #应用的描述
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 #应用版本
1.2 目标服务器信息
用户查询获取服务器的基本定义及信息，涉及以下模块信息：
servers
是否必选：必选
对象类型：[Server Object]
这个模块主要提供和目标服务器的连接信息，如果这个模块没有定义url，根据规范会自动生成一个url为/的Server Object。
例如：
servers:
- url: https://development.gigantic-server.com/v1 #必选，
description: Development server #非必选，url描述
1.3 API路径及定义
查询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: oauth3
flows:
implicit:
authorizationUrl: http://example.org/api/oauth/dialog
scopes:
write:pets: modify pets in your account
read:pets: read your pets
2 如何使用OAS 设计可扩展的OpenAPI
OpenAPI规范包含一组有关如何设计REST API的强制性准则，首推协议优先的方法，而非实现优先，因此需要首先设计API接口，然后实现协定接口的代码。
如何实现一个优雅的API是一个非常具有挑战性的工作，开发者需要在庞大的后端系统的支持下，通过合适的方式将API暴露出去，除去单词拼写，路径设计等以外，设计优良的OpenAPI往往具有以下特性：
l 单一职责
单一职责是软件工程中一条著名的原则，实际在设计API时应确保每个API具有单一核心的职责，当某个API职责发生改变时不应该导致其他API发生故障和风险。OAS中不同的API可以在paths模块中引用多个schema，当我们设计新的API或者扩展原有API功能时，如果发现多个API多次引用相同schema，需重点审视每个API是否仍然保持单一职责。
l 抽象API
合适的抽象API 与业务无关的，更通用，而且方便扩展。 具体的API接口设计能解决特定的问题，但是在系统的扩展性和普遍适用性上则相应欠缺，因此需要针对特定的场景分析，避免over-designed（过度设计）和under-engineering（懒惰设计）。
举个简单的例子，我们设计一个paths为/dog的API，那么这个API返回的是具体dog的相关信息，而如果我们进行抽象设计一个paths为/pet的API，将dog作为参数配置在components的parameters中，这样该API的扩展性进行了提升，后续扩展其他宠物比如cat的业务可以在不改变API路径的基础上进行开发，只需要更新component的parameters即可。
l 收敛API
提供给用户的OpenAPI最好支持批量数据处理，而不是让用户一次一次地调用。通过考虑多个API间的关联性，让用户体会到API的简洁性。举例来说，如果用户有可能在调用 API2之前需要API1的结果，那么API提供者应该把API1和API2进行包装。这会减轻用户的记忆负担，API收敛需要符合最少知识的原则，作为用户应该对他所使用的系统有最少的了解，而不是过多介入到系统的细节中，因此在设计API时候，在满足用户诉求的情况下，components模块字段越少越好。设计者往往容易在收敛API时候出现无法保证单一职责的原则的情况，好的设计需要在两者之间取得一个平衡，聚焦于最终的目的:让使用者快好省的用起来。
l 扩展机制
在设计API时需要考虑未来可扩展性，为后续API兼容历史API提供支持。一方面便于开发者自身增加功能，另一方面用户也能参与进来，共建API生态。通过设计定义OAS，可以方便的按照OAS架构设计出面向对象、扩展性良好的API。
l 版本控制
版本控制其实是扩展的一部分，鉴于大量项目在版本控制方面都做的比较糟糕，诸如随心所欲的版本命名、前后格式不一致的版本设定、没有规范的功能迭代，因此在大版本号不变的情况下，需要保障API向前兼容。当API的大版本号改动时，意味着API整体有大的改动，很可能不兼容之前的API，同时可以提醒用户需要查询API更新文档进行适配，否则用户可能在更新API之后出现各种各样难以预测的故障。反之，如果修改小版本号则意味着这是个向前兼容的优化升级，用户可以在例行更新中采用新的API。这种和用户约定好的默契，可以激发用户采用新版本的热情，而不是永远不升级依赖。
l 面向扩展开发
在通过OAS定义完相关信息之后，优雅的OpenAPI在开发过程中应着重思考API的可配置性，API的实现应该面向修改开放的，因此需要将相关诸如参数校验、字段长度等配置项进行抽取，在提供默认配置项的前提下可配置可修改，同时应当允许配置项的新增，例如引入java的可变参数类型等，这样当OAS文档进行修改时，可以尽可能的较少整体API实现的变动量。
以上列举了优雅的OpenAPI所具有的部分特性，与其说OAS设计规范是一个强制的法则，不如说是一种引导式框架，开发者通过遵循规范从而实现高效的敏捷迭代。
当完成OpenAPI的设计开发之后，我们需要将API托管到合适的平台上进行能力开放，优秀的平台减少API提供者的工作量，抽取公共能力使API提供者更加专注于业务功能开发。华为云的API网关集成了监控、流控、负载均衡等一系列功能，可以为开发者提供高性能、高可用的API 托管服务，实现个人、企业API能力的快速开放。
感谢你的阅读，相信你对“基于OAS设计可扩展OpenAPI的示例分析”这一问题有一定的了解，快去动手实践吧，如果想了解更多相关知识点，可以关注创新互联网站！小编会继续为大家带来更好的文章！
当前文章：基于OAS设计可扩展OpenAPI的示例分析
文章转载：http://scyanting.com/article/gcgeis.html
