标签：swagger

入门

Swagger 给我们提供了两个有用的工具： Swagger Editor 和 Swagger Inspector 和一个 API 托管平台 SwaggerHub。其中 Swagger Hub 是一个可以让个人拥有 3个公共 API 文档仓库和一个私有仓库的在线 API 文档生成以及Mock API Server的一整套服务，使用 YAML 以及 Open API Specification 编写出能够使 Swagger 自动生成文档的 API。下面，笔者将会带大家学习 Swagger 这个极好的 API 编写平台。

我们打开 Swagger 后，我们就会来到 Swagger 的首页，点击 “Try Swagger Hub” 就可以来到 “Swagger Hub”的首页，再接着 “Sign Up Free” 便可以进入注册界面，当然可以直接进入注册界面如下所示：

接下来我们分别输入“User Name”, “Email”, 以及 “Password” 点下 “SIGN UP” 静候佳音即可，完成后可以看到下面的界面，输入组织名称 “Name your Organization”点下按钮即可，当然你可以不管它直接进入 Swagger Hub。

接着来到 Swagger Hub 界面，新建一个 Swagger API 。点击 “Create New API”

OpenAPI version 默认为 2.0 如果有兴趣也可以使用 3.0，Template 为一些基础的 API 文档，这里选择的是宠物商店(Petstore)模板，在 Name 中输入一个“test”，可见性（Visibility）选择“Public”，Public 可以直接让别人看到你的API，通常不告诉别人几乎不大可能看到，看到也没多大关系。而 Private 就相反了，只有你和协作者才可以看到。现在可以点击“Create API”继续下去了。 成功后会来到 Design View 如下图所示：

绿色区域是导航视图、编辑器视图、文档视图三个视图的显示，隐藏，编辑器与导航可以单独隐藏，但至少显示一个。蓝色区域便是导航视图，可以看到由一个可以展开和折叠的“Tags”做页标并以HTTP请求方法和请求路径的项目构成。点击导航的项目可以很方便地导航到该项目在编辑器中定义的位置。紫色区域为文档区域，在文档区域可以查看 Open API 给我们解释并生成的 API 文档。深蓝色区域与一般高亮的编辑器没什么特别之处。编辑器编写的 Open API 代码会实时更新到那里文档区域和导航区域。橘色区域可以调整编辑器的文字大小，白天、夜晚背景色和评论。评论可以帮助组织或者团队之间的协作和沟通。粉红色区域则是编辑器所编写的 Open API 代码能否顺利通过验证，可以点击它展开来看到不正确的地方。

文档区域中比较简明易懂，参数列表，响应码以及相应描述和响应结果一应俱全。左上方的“Try it out”还可以直接使用 Mock API Server 进行返回结果。

Model 文档直接显示了这份 Open API 所用到的实体，对数据库设计很方便啊！显示的方式与 JSON 格式相差不大。 接下来，笔者将会讲述一些必要的 YAML 知识和 Open API 知识。

YAML 结构

YAML 使用缩进（这里使用两个空格）作为嵌套层，类似与 Python 使用缩进界定代码块。与 JSON 类似可以有 number, string, object, array 类似的概念，故这里使用来简单地介绍 YAML。这里给出 YAML 的官网以及会用到的一些写法帮助大家简单地了解一下 YAML 。 YAML 的基础写法

key: value
key:
  key1: value
  key2: value

YAML number 的写法

grade: 100

YAML string 的写法，使用第二种允许预先换行。

title: Hello world
title: |
  Hello world
  this is a good example

YAML object 的写法

person:
  name: hello
  age: 18
  gender: male

YAML array 的写法

persons:
- name: hello
  age: 18
  gender: male
- name: mike
  age: 20
  gender: male

Open API 结构

简述

Open API 组成很直观，顶头注明Open API 的版本，使用一个 info object，介绍这份 Open API, 并使用 tags array，描述这份 Open API 中用到的标签，使用 paths object，描述各部分 REST API 中的 HTTP 链接 。securityDefinitions object 定义了有关登录和权限的限定。definitions object 定义了各个 Model，externalDocs object 则定义这份 Open API 的额外信息，后面的是 Swagger Hub 给我们提供的 Mock Server。

info object

info object 的内容很直观，这份API 相关的描述，版本，标题， 联系方式，开发协议等等。

tags array

如同前面所言，数组元素使用“- ”开头然后写key: value 对构成，每一个“- ”及其缩进的内容为一个 YAML object。

paths object

paths object的写法很明显，先是一个API 请求路径 “/pet” object 接着是一个 “请求方法” object，然后写明这个请求 object 的 tags array，写上“summary”说明这个 API 是拿来干什么的，operationId 用来标识整个 API ，consumes (消耗)，意味着该 API 可以接受怎样的数据(accept header)。produces (产出) 意味着API会产生什么类型的响应(content-type)。parameters，很显然是该 API 接受的参数。responses 则是定义响应。security 则是相应的权限。Open API 允许我们在一个请求路径 object 下接着写其它 请求方法 object 的 API。如上面没有显示完全的“put”。

在 securityDefinitions object 中，petstore_auth 用于 oauth2 的认证，api_key 用于 API 调用的认证（类似与 Web 中经常放在地址后面的 Token ）。如果是 cookie 的认证则简单的由 api_key auth 的 i n 改为 “basic” (2.0) 或者 “cookie ” (3.0)。

在 definitions object 中，每个像 Order, Category 一样层级的都是Model， 这些 Model 在编写 API 的参数，输出结果中在 schema 属性中进行引用。引用方式一般是以下的方式：

schema:
  $ref: '#/definitions/ModelName'

写法如如英文所言，先指定好 type, 接着写属性 properties，properties 中为一个Model 的属性名 object 指定该属性的类型，在这里依然可以使用 schema 进行应用。更多 Open API 的说明可以查看 Open API 规范。