什么是 openAPI ?

OpenAPI 是什么?

Open API 即开放 API，也称开放平台。 所谓的开放 API（OpenAPI）是服务型网站常见的一种应用，网站的服务商将自己的网站服务封装成一系列
API（Application Programming Interface，应用编程接口）开放出去，供第三方开发者使用，这种行为就叫做开放网站的 API，所开放的 API 就被称作 OpenAPI（开放 API ）。

RESTful API 是什么?

什么是 REST？

Representational State Transfer，翻译是”表现层状态转化”。可以总结为一句话：REST 是所有 Web 应用都应该遵守的架构设计指导原则。
面向资源是 REST 最明显的特征，对于同一个资源的一组不同的操作。资源是服务器上一个可命名的抽象概念，资源是以名词为核心来组织的，首先关注的是名词。REST 要求，必须通过统一的接口来对资源执行各种操作。对于每个资源只能执行一组有限的操作。

什么是 RESTful API？

符合 REST 设计标准的 API，即 RESTful API。REST 架构设计，遵循的各项标准和准则，就是 HTTP 协议的表现，换句话说，HTTP 协议就是属于 REST 架构的设计模式。比如，无状态，请求-响应。。。

Swagger 是什么?

Swagger™ 的目标是为 REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过 Swagger 定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger 去掉了调用服务时的很多猜测。

举个例子：
现在的互联网充满了一个又一个信息孤岛和大量的碎片化的数据，用户想知道一些资讯，必须在不同的网站上跑来跑去.比如看电影，首先去google map查看周围的电影院，然后去大众点评网查看对这家电影院的评论，然后去电影院的网站上看看今天有什么电影上映。然后支付网站进行电子购票.整个过程非常繁琐，数据之间没有关联.充斥着大量的异构系统. 
为了解决这些问题.我们引入了openapi的概念.通过openapi,数据提供商开放了自己的数据，通过mashup将信息孤岛连接起来.整合这些信息碎片. 

如果google,大众点评网，电影院，支付宝均开放自己的openapi.然后有一个mashup程序将他们整合起来.那么用户就能体验一站式购物.进这个网站，找到电影院，查看电影院评价，如果评价好，查看电影院上映什么节目。电子订票.然后就能直接杀过去了。省时省力 。

四类api ：

同步服务api: 普通的Http无状态单次请求和响应 
异步服务api: 应用于服务提供商提供的服务无法在当时处理完毕，先返回一个请求响应，当服务处理结束以后再将服务处理结果返回给服务调用者 
订阅服务api: 类似rss.服务调用者只需要订阅服务即可获得服务提供商推送的服务内容 
大数据量上传api: 上传文件 

什么是oauth? 

OAuth协议致力于使网站和应用程序（统称为消费方）能够在无须用户透露其认证证书的情况下，通过API访问某个web服务（统称为服务提供方）的受保护资源。更一般地说，OAuth为API认证提供了一个可自由实现且通用的方法。 

什么是openid? 

OpenID 是一个以用户为中心的数字身份识别框架，它具有开放、分散、自由等特点 

什么是Mashup? 

mashup是糅合，是当今网络上新出现的一种网络现象,将两种以上使用公共或者私有数据库的web应用，加在一起，形成一个整合应用。一般使用源应用的api接口，或者是一些rss输出（含atom）作为内容源，合并的web应用用什么技术，则没有什么限制。 
 

OpenAPI规范

OpenAPI规范始于Swagger规范，经过Reverb Technologies和SmartBear等公司多年的发展，OpenAPI计划拥有该规范（捐赠之后），OpenAPI Initiative在GitHub上托管社区驱动的规范。

 

规范是一种与语言无关的格式，用于描述RESTful Web服务，应用程序可以解释生成的文件，这样才能生成代码、生成文档并根据其描述的服务创建模拟应用。

 

什么是API优先开发？

应用程序向云环境这一演变趋势为更好地集成服务和增加代码重用提供了机会，只要拥有一个接口，然后通过该接口，其他服务的应用程序就可以与你的应用程序进行交互，这是向其他人公开你的功能，但是，开发API却不应该是在开发后才公开功能。

 

API文档应该是构建应用程序的基础，这个原则正是API-First(API优先)开发的全部内容，你需要设计和创建描述新服务与外部世界之间交互的文档，一旦建立了这些交互，就可以开发代码逻辑来支持这些交互。让我们来看看这种方法带来的好处。

 

API-First如何使您的组织受益

当你的组织从API文档开始时，这允许团队在开发过程中更快地开始彼此交互。API文档是应用程序与使用它的人之间的合同。

 

内部开发可以在API合同背后进行，而不会干扰使用它的人的努力，计划使用你的应用程序的团队可以使用API​​规范来了解如何与你的应用程序进行交互，甚至在开发之前。他们还可以使用该文档创建用于测试其应用程序的虚拟服务。

 

OpenAPI文档的剖析

该规范的当前版本是3.0.1版，并在OpenAPI GitHub存储库中进行了详细记录。但是，如果你像我一样，我更喜欢看一个规范的例子，而不是通过描述文档描述每个可能的部分的明确的技术细节。

 

让我们看一个描述服务API的简单API文档，它允许用户创建，修改，检索和删除用户首选项。您可以在SwaggerHub上完整地查看此API 。

 

OpenAPI文档有三个必需的部分或对象：

 

1. openapi - OpenAPI规范版本的语义版本号

2. info - 有关API的元数据

3. paths - API的可用路径和操作

 

你可以根据需要包含其他对象。其他对象包括安全性，服务器，标签和组件。

 

<span style="color:#333333">openapi: 3.0.1 info: version: <span style="color:#00bb00">"1.0.0"</span><span style="color:black"> title: 用户指导API description: 这是一个支持用户设置的创建，修改，检索和删除。 <p> </span></span>

 

openapi对象声明了用于文档的规范的版本。该版本对于用户理解文档的结构至关重要，更重要的是，对于可能为了验证目的而获取文档或创建虚拟服务的任何工具，info对象提供有关API本身的基本信息。标题和版本是必填字段，我们可以选择包含其他信息，例如说明，联系和许可信息。

 

路径对象

 

 

paths路径对象是API文档的核心。此对象详细说明了可与应用程序交互的路径，可用的方法以及这些交互包含的内容的详细信息。该对象包括请求参数和预期结果：

 

paths: /preference: get: summary: 根据ID发现用户设置 description: 返回用户设置 operationId: getPreferenceById parameters: - name: id in: query description: 这是返回一个用户设置的ID required: true schema: type: string responses: '200': description: 请求成功 content: application/json: schema: $ref: '#/components/schemas/Preference' '400': description: 无效 ID '404': description: 用户设置没有发现 <p>

 

上面的摘录描述了按ID检索用户设置的GET请求路径，这些属性大多是不言自明的。值得注意的是HTTP 200响应的模式。$ ref属性引用文件中其他位置的对象，它是用于多个路径的描述：

#/components/schemas/Preference的结构如下：

 

components: schemas: Preference: type: object required: - userId - preferenceName - status properties: userId: type: string format: uuid preferenceName: type: string preferenceValue: type: string status: type: string description: Preference Status enum: - test - enabled - disabled - delete <p>

在另外一个地方定义组件并引用它，这种方式能让我们重用相同的定义并使我们的OpenAPI合同更易于管理。

 

在swaggerhub有在线编辑器可以体验。