『Swagger 上手』

大纲

问题
RestfulAPI

API

动作
请求：Url、Body
返回信息：Status_code、Response

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

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

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

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

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

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

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

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

1. 思考

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

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

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


GET: /api/v1/designer/paas/{paasid}

Request: null

Response:
  - 200
  - {
      paasidinfo: ""
  }
  
  - 404
  - {
      status: no exist the paasid
  }



curl http://127.0.0.1:5000/api/v1/designer/paas/admin_123

200
{
    paasinfo: "create new paasid : admin_123"
}

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

http: 动作：Get、Post、Put、Delete
URL：访问路径：带参数和不带参数
返回信息：状态码和返回信息

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

2. Swagger 是怎么做的

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

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

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

3. 配置文件的形式

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

json
yaml
ini

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


{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Simple API",
        "description": "A simple API to learn how to write OpenAPI Specification"
    },
    "schemes": [
        "https"
    ],
    "host": "simple.api",
    "basePath": "/openapi101",
    "paths": {
        "/persons": {
            "get": {
                "summary": "Gets some persons",
                "description": "Returns a list containing all persons.",
                "responses": {
                    "200": {
                        "description": "A list of Person",
                        "schema": {
                            "type": "array",
                            "items": {
                                "properties": {
                                    "firstName": {
                                        "type": "string"
                                    },
                                    "lastName": {
                                        "type": "string"
                                    },
                                    "username": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

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

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


[hostname]
127.0.0.1

[name]
xiewei

[server]
10.100.100.100, 10.100.100.101

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

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
host: simple.api
basePath: /openapi101

paths:
  /persons:
    get:
      summary: Gets some persons
      description: Returns a list containing all persons.
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string

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

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

4. 配置文件的内容

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

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

总结下来有下面三种：

键值对：key: value
数组
纯量：整型、字符串、布尔型

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

键值对

{
    name: xiewei
}

name: xiewei

数组

name :["xiewei1", "xiewei2", "xiewei3"]


name:
  - xiewei1
  - xiewei2
  - xiewei3

纯量

"xiewei"
false
123

xiewei
123 
true

5. Swagger 的使用

离线形式

下载地址： Swagger
浏览器打开 index.html 文件

在线形式

访问地址：在线版本

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

微信截图_20180130214149.png

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

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

即：

http 动作
url
请求体
返回信息

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

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

API 的描述信息
API 的URL 信息
API 的操作
- http 动作
- url
- 请求
- 响应

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


swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters."
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"

schemes:
- "http"
paths: {}

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

info、title、description 、version 等表示的是API 版本信息
host、basePath、schemes 等表示的是API 的URl 信息
paths 下面的值表示的是API 的操作

效果大概是这样的：

微信截图_20180130214245.png

下面举例：

原始API 为：

POST  /api/v1.0/designer/paas/{paasid}
Request
{
  "git": {
    "addr":"ssh://ipaddr/path/.git",
    "branch":"master"
  }
}

Normal response codes: 201
{
    "passid":"xxxxx",
    "local_git":"ssh://localhost/paasdata/confcenter/{paasid}/pdmng/.git"
}

Error response codes: 400
{
    "desc": "error reason"
}

提取下：

http 动作为：POST
URL 中需要传入参数 paasid
body 体为一个 json 体
返回信息为两个：一个成功201、一个失败400，以及相应的返回值

在Swagger 中这样处理：

path:
  /api/v1.0/designer/paas/{paasid}:
    post:
      tags:
        - paas
      produce:
        - application/json
      parameters:
        - name: paasid
          type: string
          in: path
          required: true
        - name: gitinfo
          in: body
          required: true
          schema:
            properties:
              git:
                type: object
                required:
                  - addr
                  - branch
                properties:
                  addr:
                    type: string
                    description: git address
                  branch:
                    type: string
                    description: git branch
      response:
        201:
          description: create paas id success
          shcema:
            properties:
              paasid:
                type: string
                description: paasid
              local_git:
                type: string
                description: address in localhost
        400:
          description: create paas id failed
          schema:
            properties:
              error:
                type: string
                description: the reason of error

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

url 信息：动作post，以及响应类型：application/json
parameters: 处理的是传入的参数
responses: 处理的是响应的信息

逐步分析：

添加访问路径和http动作

paths:
  /api/v1.0/designer/paas/{paasid}:
    post:
      tags:
        - paas

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

添加处理信息

produces:
  - application/json

即：响应内容格式json

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

parameters:
  - name: paasid
    in: path
    description: create paasid
    required: true
    type: string
  - name: Gitinfo
    in: body
    description: git info of body
    required: true
    schema:
      properties:
        git:
          type: object
          required:
            - addr
            - branch
          properties:
            addr:
              type: string
            branch:
              type: string

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

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

{
  "git": {
    "addr":"",
    "branch": ""
  }
}

上文：

schema 模式来描述具体的参数的信息：
- type: 参数类型：integer, string, array, boolean等
- in: 表示参数是在url 路径里，还是在body 里，或者是在请求里
- description: 对参数的介绍
- required: 表示是否一定需要该值，默认false

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

即：状态码 201、400

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

嵌套处理 type ： object
properties 属性值
type：属性的类型
description: 属性的介绍

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

编写路径和动作
定义参数
定义响应信息

最终效果如下：

微信截图_20180130215708.png

微信截图_20180130214149.png

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

6. 参考文献

ChangeLog

2018.01.29 成文
2018.01.30 修订