1.使用界面预览:
2.安装教程:
先到git下载:https://github.com/swagger-api/swagger-editor;
然后直接打开index.html 或者如上图创建一个服务器,访问该项目;然后就可以看到如1中的效果了。
具体使用教程可以参考3.
3.使用教程:
Swagger是一种Rest API的 简单但强大的表示方式,标准的,语言无关,这种 表示方式不但人可读,而且机器可读。 可以作为Rest API的交互式文档,也可以作为Rest API的形式化的接口描述,生成客户端和服务端的代码。
本文介绍Swagger以下内容:
- Swagger API Spec,描述Rest API的语言
- Swagger UI,将Swagger API Spec以HTML页面展现出来的模块
- 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,附加的外部文档
下面是一个操作的描述
/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如下图所示:
可以访问在线Swagger UI:http://petstore.swagger.io/
使用Swagger UI很容易,只要把github项目(https://github.com/swagger-api/swagger-ui)下载到本地:
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中添加下面的文字。
<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的表现方式
比如:
- docExpansion:指定操作的描述是收起的还是展开的
- supportedSubmitMethods:允许哪些HTTP方法的文档带Try It!的按钮
- operationsSorter:指定操作安装什么排序
更多请参考官网的文档。
Swagger Editor
顾名思义,Swagger Editor是Swagger API Spec的编辑器,Swagger API Spec有2中格式,yaml和json,Swagger Editor使用yaml进行编辑,但允许导入和下载两种格式的文件。在yaml编辑器的右面有所见即所得的预览。
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并跑起来的指令
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对于上述的接口编写文档,示例如下:
#必要字段!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即为1和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: 别名