『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.101yaml 这种形式阅读性最好，其次可以对文本内容进行注释，整体的效果最佳，很适用于配置文件。
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
123xiewei
123
true5. 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 修订