基于OAS设计可扩展OpenAPI

随着互联网行业的兴起，开发模式已逐步转换为微服务自治：小团队开发微服务，而后经过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: 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: oauth2
         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能力的快速开放。

关于API网关的详情，能够点击下面连接进行体验：https://console.huaweicloud.com/apig/?region=cn-north-1#/apig/expdemo