干货 Swagger 上手指南

每天读一篇一线开发者原创好文

大纲

问题

RestfulAPI

API

动作

请求：Url、Body

返回信息：Status_code、Response

在开发过程中，经常会遇到和其他组件或者服务进行交互的情况，和服务器交互，好理解，平时的上网就是在和服务器交互：向服务器发送请求，服务器接收到请求之后，根据请求的动作，进行相应的动作响应。

可以看出这种方法方式是通过：发送请求，返回响应的这一套动作进行的，即客户端、服务器模式，发送请求的一端一般认为是客户端，返回响应的一端认为是服务器端。

软件设计领域，将这一套机制统一起来，方便进行通信：即 Restful api。

简单的来说：比如需要开发一个软件，软件的细节不让使用者看到，但是使用者又有可能需要访问到软件服务上的某些资源。这个时候就应该定义一套API, 让使用者调用这套API就能获取或者更新或者删除服务上的资源。

最近的接触的业务开发相互之间的访问都是通过API 访问，相互之间无需知道内部细节。

在这个过程中，约定的API 经常随着开发的进行而需要进行改动，有对请求进行更改的，有对返回信息进行修改的，也有对状态码定义的修改的。变动的API 对开发的要求很高，导致进行重复或者无效的开发。

伟大的开源领域一定有相应的解决方法。

Swagger 就是这么一套简单但功能强大的API 表达工具。本教程就是让读者学会使用这个工具的使用。

1. 思考

让你设计这套API 可视化工具，你会怎么设计？

和API 相关的又有哪些东西需要呈现？

举个例子：未经可视化的API 的一般定义会是这样

从上面的示例和API 相关的东西包括;

http: 动作：Get、Post、Put、Delete

URL：访问路径：带参数和不带参数

返回信息：状态码和返回信息

主要是这三类。这三类定下来，API 基本就定下来。

2. Swagger 是怎么做的

平时定义这么一套API 的方法大概和举例差不多，那Swagger 是如何做的呢？

Swagger 是通过定义一个配置文件的形式，这套配置文件有它约定的语法，再通过对配置文件的处理，可视化出API。除此之外，通过Swagger 生成的API, 可以得到交互式的文档，自动生成代码的SDK以及API 的发现特性等。

本文暂探讨配置文件的编写，生成可视化的API。

3. 配置文件的形式

一般的配置文件的形式有这么三种：

json

yaml

ini

这三种很常见，其中json 的方式很普遍，但是可读性不好，尤其是嵌套处理的字段更不好阅读。

上文这个json 体很容易出错，如果没有静态格式检查工具，很容易漏掉{}

ini 这种形式很简单，但也适用于简单场合，不易处理复杂的嵌套场景

yaml 这种形式阅读性最好，其次可以对文本内容进行注释，整体的效果最佳，很适用于配置文件。

可以看出整体的这种键值对的形式阅读的效果很好。

任何编程语言，对json, yaml，ini 格式的配置文件的处理和很方便，接口都很简便，比如 Python，Go

4. 配置文件的内容

简单分析完配置文件的格式的优缺点，再来分析下配置文件的内容。

这里到不是具体的分析文件内容的值，而是分析配置文件的内容的数据类型。

总结下来有下面三种：

键值对：key: value

数组

纯量：整型、字符串、布尔型

不管是Json 或者 Yaml 文件的组成都是这三种形式的混合

键值对

数组

纯量

5. Swagger 的使用

离线形式

下载地址： Swagger

浏览器打开 index.html 文件

在线形式

访问地址：在线版本

打开后都存在一个默认的配置文件，左边是配置文件，右边是可视化结果。

配置文件看上去很复杂，其实都是在实现这么一句话：

API的基本组成部分，包括提供给API消费者的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。

即：

http 动作

url

请求体

返回信息

Swagger 定义了一些特殊的字段来实现这个目标，我们只需要熟悉一些特殊的字段，就能实现API 的定义。

整个Swagger 配置文件的格式为 yaml。梳理了下，配置文件主要包括下面三个部分：

API 的描述信息

API 的URL 信息

API 的操作

http 动作

url

请求

响应

一个简易的配置文件形式大概是这样的：

上面的信息不是所有的都是必须的。

info、title、description 、version 等表示的是API 版本信息

host、basePath、schemes 等表示的是API 的URl 信息

paths 下面的值表示的是API 的操作

效果大概是这样的：

下面举例：

原始API 为：

提取下：

http 动作为：POST

URL 中需要传入参数 paasid

body 体为一个 json 体

返回信息为两个：一个成功201、一个失败400，以及相应的返回值

在Swagger 中这样处理：

分解下，上文写配置文件实现的API：

url 信息：动作post， 以及响应类型：application/json

parameters: 处理的是传入的参数

responses: 处理的是响应的信息

逐步分析：

添加访问路径和http动作

即：POST: /api/v1.0/designer/paasid/

添加处理信息

即：响应内容格式json

定义参数：URL 参数，和传入的参数

即：url 中需要传入一个参数 paasid

同时body 体需要传入一个json 格式的参数

上文：

schema 模式来描述具体的参数的信息：

type: 参数类型：integer, string, array, boolean等

in: 表示参数是在url 路径里，还是在body 里，或者是在请求里

description: 对参数的介绍

required: 表示是否一定需要该值，默认false

定义响应信息：状态码和响应值

即：状态码 201、400

响应信息也使用 schema 模式来描述具体的参数信息：

嵌套处理 type ： object

properties 属性值

type： 属性的类型

description: 属性的介绍

总结：编写配置文件，可视化API 的核心就是在处理path

编写路径和动作

定义参数

定义响应信息

最终效果如下：

更多用法需要探讨，学习稍微有点成本，但都可以学会。

6. 参考文献

RestfulAPI

Yaml

Swagger教程

ChangeLog

2018.01.29 成文

2018.01.30 修订