Swagger editor 简介

/pets/findByTags:
get:
tags:
- pet
summary: Finds Pets by tags
description: Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.
operationId: findPetsByTags
produces:
- application/json
- application/xml
parameters:
- in: query
name: tags
description: Tags to filter by
required: false
type: array
items:
type: string
collectionFormat: multi
responses:
“200”:
description: successful operation
schema:
type: array
items:
$ref: “#/definitions/Pet”
“400”:
description: Invalid tag value
security:
- petstore_auth:
- write_pets
- read_pets1.使用界面预览：

img

2.安装教程：

img

先到git下载：https://github.com/swagger-api/swagger-editor;

然后直接打开index.html 或者如上图创建一个服务器，访问该项目；然后就可以看到如1中的效果了。

具体使用教程可以参考3.

3.使用教程：

Swagger是一种Rest API的 简单但强大的表示方式，标准的，语言无关，这种 表示方式不但人可读，而且机器可读。 可以作为Rest API的交互式文档，也可以作为Rest API的形式化的接口描述，生成客户端和服务端的代码。

本文介绍Swagger以下内容：

  1. Swagger API Spec，描述Rest API的语言
  2. Swagger UI，将Swagger API Spec以HTML页面展现出来的模块
  3. Swagger Editor，Swagger API Spec的编辑器

Swagger API Spec/Open API Spec

Swagger API Spec是Swagger用来描述Rest API的语言，类似于描述Web服务的WSDL。Swagger API可以使用yaml或json来表示。 2016年1月，Swagger将Spec捐献给Open API Initiative (OAI)，成为Open API Spec的基础。

Swagger API Spec包含以下部分：

  • swagger，指定swagger spec版本，2.0

  • info，提供API的元数据

  • tags，补充的元数据，在swagger ui中，用于作为api的分组标签

  • host，主机，如果没有提供，则使用文档所在的host

  • basePath，相对于host的路径

  • schemes，API的传输协议，http，https，ws，wss

  • consumes，API可以消费的MIME类型列表

  • produces，API产生的MIME类型列表

  • paths，API的路径，以及每个路径的HTTP方法，一个路径加上一个HTTP方法构成了一个操作。每个操作都有以下内容：

    • tags，操作的标签
    • summary，短摘要
    • description，描述
    • externalDocs，外部文档
    • operationId，标识操作的唯一字符串
    • consumes，MIME类型列表
    • produces，MIME类型列表
    • parameters，参数列表
    • responses，应答状态码和对于的消息的Schema
    • schemes，传输协议
    • deprecated，不推荐使用
    • security，安全

  • definitions，定义API消费或生产的数据类型，使用json-schema描述，操作的parameter和response部分可以通过引用的方式使用definitions部分定义的schema

  • parameters，多个操作共用的参数

  • responses，多个操作共用的响应

  • securityDefinitions，安全scheme定义

  • security，安全声明

  • externalDocs，附加的外部文档

下面是一个操作的描述

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/pets/findByTags:
    get:
      tags:
        - pet
      summary: Finds Pets by tags
      description: Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.
      operationId: findPetsByTags
      produces:
        - application/json
        - application/xml
      parameters:
        - in: query
          name: tags
          description: Tags to filter by
          required: false
          type: array
          items:
            type: string
          collectionFormat: multi
      responses:
        "200":
          description: successful operation
          schema:
            type: array
            items:
              $ref: "#/definitions/Pet"
        "400":
          description: Invalid tag value
      security:
        - petstore_auth:
          - write_pets
          - read_pets

参数的描述包括：

  • name，名字

  • description，描述required，是否必须

  • in，位置

    • Path
    • Query
    • Header
    • Body
    • Form

  • （对于Body类型的参数）

    • schema，数据类型，可以详细描述，也可以引用definition部分定义的schema

  • （对于Body类型以外的参数）

    • type，类型
    • format，数据格式
    • allowEmptyValue，是否允许空值
    • items，对于Array类型
    • collectionFormat，对于Array类型
    • default，缺省值

Swagger API Spec对你Rest API的每一个操作的请求消息的参数（Path,Query,Body,Form），响应消息的状态码和消息体的json结构都进行了详细的描述。不仅可以供给使用API的开发者学习，而且是对Rest API接口的形式化的抽象。

我们完全可以把Swagger API Spec当作一个API接口的设计语言，就像CORBA IDL或Web服务的WDL一样，先定义Rest API的操作参数和应答消息，再着手实现这些Rest API，这对Rest API日后的维护也提供了一个设计文档。

Swagger UI

Swagger UI是Swagger中用于显示Rest接口文档的项目，项目由一组HTML，JavaScript和CSS组成，没有外部依赖。Swagger UI可以根据Swagger Spec的json动态生成漂亮的帮助文档。支持常见浏览器。

Swagger UI如下图所示：

img可以访问在线Swagger UI：http://petstore.swagger.io/

使用Swagger UI很容易，只要把github项目（https://github.com/swagger-api/swagger-ui）下载到本地:

1
git clone https://github.com/swagger-api/swagger-ui.git

然后用浏览器打开dist/index.html就可以。当然也可以放到HTTP Server下通过HTTP协议访问。

在浏览器地址栏中，可以在index.html后添加url参数，就可以自动打开指定的Rest APi的json描述。如：file:///E://swagger-ui/dist/index.html?url=http://petstore.swagger.io/v2/swagger.json

通过编辑index.html，就可以对Swagger UI进行定制，包括：

\1. 中文显示

在html header中添加下面的文字。

1
2
<script src='lang/translator.js' type='text/javascript'></script>
<script src='lang/zh-cn.js' type='text/javascript'></script>

中文翻译位于/lang/zh-cn.js文件，如果有什么不合适的翻译，可以直接修改。

\2. 指定Swagger UI的表现方式

比如：

  1. docExpansion：指定操作的描述是收起的还是展开的
  2. supportedSubmitMethods：允许哪些HTTP方法的文档带Try It!的按钮
  3. operationsSorter：指定操作安装什么排序

更多请参考官网的文档。

Swagger Editor

顾名思义，Swagger Editor是Swagger API Spec的编辑器，Swagger API Spec有2中格式，yaml和json，Swagger Editor使用yaml进行编辑，但允许导入和下载两种格式的文件。在yaml编辑器的右面有所见即所得的预览。

img

Swagger Editor的Live Demo：Swagger Editor

Swagger Editor的安装也很方便，

下载最新的发布版：https://github.com/swagger-api/swagger-editor/releases/download/v2.10.1/swagger-editor.zip

然后解压到文件夹，用HTTP Server将静态文件加载起来，下面是安装node.js的http server并跑起来的指令

1
2
3
4
npm install -g http-server
wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.1/swagger-editor.zip
unzip swagger-editor.zip
http-server -p 8080 swagger-editor

http server启动后，就可以在浏览器中输入地址进行编辑了。

文件菜单提供了主要的功能

  • New，创建新的文件
  • Open Example，打开内建Swagger API Spec的示例
  • Paste Json，将剪贴板的内容贴到编辑器中，取代当前的内容。在Paste之前一定要先下载编辑中的内容
  • Import URL/Import File，导入已有的Swagger API Spec，可以是yaml或json格式的
  • Download YAML/Download JSON，将编辑的结果下载到本地。

代码生成

Swagger支持根据Swagger API Spec生成客户端和服务端的代码，支持很多语言和框架。这部分我还没有深入使用。

4.demo：

通过Swagger对于上述的接口编写文档，示例如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
#必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件
swagger: '2.0'
#必要字段！描述API接口信息的元数据
info:
  #接口标题
  title: swagger说明文档　
  #接口文档的描述
  description: 学习Swagger
  #版本号
  version: 1.0.0
#Swagger会提供测试用例，host指定测试时的主机名，如果没有指定就是当前主机,可以指定端口．
host: 127.0.0.1
#定义的api的前缀，必须已/开头,测试用例的主机则为:host＋bashPath
basePath: /api
#指定调用接口的协议，必须是:"http", "https", "ws", "wss"．默认是http.-表示是个数组元素，即schemes接受一个数组参数
schemes:
  - http
  - https
#对应与http协议头request的Accept，调用者可接受类型,默认是*/*,定义的类型必须是http协议定义的 Mime Types,RestfulAPI一般定义成application/json
#这两个是对所有接口的全局设置，在细化的接口中是还可以对应这两个属性来覆盖全局属性
produces:
  - application/json
#必要字段!定义可有可操作的API
paths:
  /users:
   #必要字段!定义HTTP操作方法，必须是http协议定义的方法
    get:
      #接口概要
      summary: 查询所有用户信息
      #接口描述
      description: 查询出所有用户的所有信息，用户名，别名
      #标签，方便快速过滤出User相关的接口
      tags:
        - User
      #返回值描述，必要自动
      responses:
        #返回的http状态码
        200:
          description: 所有用户信息或者用户的集合信息
          #描述返回值
          schema:
            #返回值格式，可选的有array,integer,string,boolean
            type: array
            #针对array,每个条目的格式,type定义为array．必要填写items
            items:
              #引用在definitions下定义的Users
              $ref: '#/definitions/User'
        #执行出错的处理
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
            #值类型
            type: object
            #定义属性
            properties:
            #属性名
              message:
                #类型
                type: string
    #即对于同一个url定义两个不同的方法，表示两个接口
    post:
      description: 注册一个用户
      #请求参数
      parameters:
          #参数key
        - name: username
          #传递方法，formData表示表单传输，还有query表示url拼接传输，path表示作为url的一部分
          #body表示http头承载参数(body只能有一个,有body不能在有其他的)
          in: formData
          #参数描述
          description: 用户名，不能使用已经被注册过的
          #参数是否必要，默认false
          required: true
          #参数类型，可选的包括array,integer,boolean,string.使用array必须使用items
          type: string
        - name: password
          in: formData
          description: 用户登陆密码，加密传输，加密存储
          required: true
          type: string
        - name: alias
          in: formData
          type: string
          description: 用户别名
          #非必要字段
          required: false
      responses:
        #返回的http状态码
        200:
          description: 通过返回值来标示执行结果　返回true表示执行成功
          schema:
             #值类型
              type: object
              #定义属性
              properties:
              #属性名
                status:
                  #类型
                  type: boolean
                  #描述
                  description: 是否成功
        #执行出错的处理
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
            #值类型
            type: object
            #定义属性
            properties:
            #属性名
              message:
                #类型
                type: string
  /users/{id}:
    #{id}表示id为请求参数，例如/users/1,/users/2都是对该API的请求，此时id即为１和2
    get:
      summary: 根据用户名id查询该用户的所有信息
      description: 查询出某个用户的所有信息，用户名，别名等
      tags:
        - User
      parameters:
        #上面接口中定义了{id}，则参数列表中必须包含参数id,并且请求类型为path
        - name: id
          in: path
          description: 要查询的用户的用户名,它是唯一标识
          required: true
          type: string
      responses:
        200:
          description: 所有用户信息或者用户的集合信息
          schema:
              $ref: '#/definitions/User'
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
              #值类型
              type: object
              #定义属性
              properties:
              #属性名
                message:
                  #类型
                  type: string
    #http定义的delete方法,删除一个资源
    delete:
      summary: 删除用户
      description: 删除某个用户的信息，被删除的用户将无法登陆
      parameters:
        - name: id
          in: path
          type: string
          required: true
          description: 用户的唯一标示符
      tags:
        - User
      responses:
        200:
          description: 通过返回值来标示执行结果　返回true表示执行成功
          schema:
             #值类型
              type: object
              #定义属性
              properties:
              #属性名
                status:
                  #类型
                  type: boolean
                  #描述
                  description: 是否成功
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
              #值类型
              type: object
              #定义属性
              properties:
              #属性名
                message:
                  #类型
                  type: string
                  #描述错误信息
    #http定义的patch方法，表示修改一个资源
    patch:
      summary: 用户信息修改
      description: 修改用户信息(用户名别名)
      parameters: 
        - name: id
          in: path
          description: 用户名,要修改的数据的唯一标识符
          required: true
          type: string
        - name: alias
          in: formData
          description: 新的用户别名
          required: true
          type: string
      tags:
        - User
      responses:
        200:
          description: 通过返回值来标示执行结果　返回true表示执行成功
          schema:
            #值类型
              type: object
              #定义属性
              properties:
              #属性名
                status:
                  #类型
                  type: boolean
                  #描述
                  description: 是否成功
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
              #值类型
              type: object
              #定义属性
              properties:
              #属性名
                message:
                  #类型
                  type: string
                  #描述错误信息
definitions:
  User:
    #值类型
    type: object
    #定义属性
    properties:
    #属性名
      id:
        #类型
        type: string
        #描述
        description: 用户的唯一id
      username:
        type: string
        description: 用户名
      alias:
        type: string
        description: 别名
WEB 框架 Swagger
Swagger

本博客所有文章除特别声明外，均采用 CC BY-SA 4.0 协议 ，转载请注明出处！