swagger学习
今天接触了swagger,不得不为它惊奇,后端接口编写测试更加的动态化,更加的满足后端人员的需求。
转;http://www.cnblogs.com/JoiT/p/6378086.html
关于 Swagger
Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因:
- Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。
- Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
- Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
- Swagger 有一个强大的社区,里面有许多强悍的贡献者。
Swagger 文档提供了一个方法,使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API,包括了比如 names、order 等 API 信息。
你可以通过一个文本编辑器来编辑 Swagger 文件,或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。
注意:用 Swagger 文件生成互动的 API 文档是最精简的,它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。
Petstore 的 Swagger 例子
为了更好的理解 Swagger ,我们现在来探索一下 Petsotre 项目的例子。记住:以下出现的 UI 都是指Swagger UI。Swagger 可以被展示成不同的视觉样式,这取决于你所使用到的视觉框架。
有三个资源:pet,store,user。
创建一个 pet
1、展开 pet 的 post 方法
2、然后单击 Model Schema 中的黄色字体的 JSON。
这里用 JSON 填充了 body value。这里的 JSON 是你必须上传的,用于创建 pet 资源。
3、将第一个 id 标签的值修改一下(你必须保证 id 值都是唯一的,并且不能从 0 开始)。
4、将 name 标签的值修改一下(最好也要唯一,方便对比结果),以下是示例代码:
{
"id": 37987,
"category": {
"id": 0,
"name": "string"
},
"name": "Mr. Fluffernutter",
"photoUrls": [
"string"
],
"tags": [
{
"id": 0,
"name": "string"
}
],
"status": "available"
}
5、单击 Try it out! 按钮,查看响应:
通过 ID 查询 pet
展开 Get 方法:pet/{petId},输入你的 petId,单击 Try it out!,你创建的 pet 就会显示在 response 中。
默认情况下,api 响应都是 xml。可以把 Response Content Type 修改为 application/json 再试一次。
返回的值将会是 JSON 格式
注意:值得强调的是 Swagger 文档一定要通过着手尝试来学习。你要通过实实在在的发送请求和查看响应来更好的理解 Petstore API 是如何工作的。但是还要注意现在你已经在你的真实Petstore数据库中创建了一个新的pet。从学习尝试 API 过渡到在生产环境中使用 API 的时候,那些测试数据你可能都需要将它们删除。
整理 Swagger 组件
Swagger 分成一些不同的块。
Swagger spec:这一块对元素的嵌套、命令等采用官方模式。如果你想要对 Swagger 文件手动编码,你必须非常熟悉 Swagger spec。
Swagger editor:这是在线编辑器,用于验证你的 YML 格式的内容是否违反 Swagger spec 。YML 是一种句法,依赖于空格和嵌套。你需要对 YML 句法很熟悉才能很好的遵守 Swagger spec 规范。Swagger 编辑器会标出错误并且给你格式提醒(Swagger spec 文件可以使用 JSON 或者 YAML 中的任意一种格式)。
Swagger-UI:这是一套 HTML/CSS/JS 框架用于解析遵守 Swagger spec 的 JSON 或 YML 文件,并且生成API文档的UI导航。它可以将你的规格文档转换成Swagger Petsotre-like UI。
Swagger-codegen:这个工具可以为不同的平台生成客户端 SDK(比如 Java、JavaScript、Python 等)。这些客户端代码帮助开发者在一个规范平台中整合 API ,并且提供了更多健壮的实现,可能包含了多尺度、线程,和其他重要的代码。SDK 是用于支持开发者使用 REST API 的工具。
一些 Swagger 的实现例子
它们大多看起来一样。你会注意到 Swagger 实现的文档都很精简。这是因为 Swagger 的展示都是互动的体验,你可以尝试请求和查看响应,使用你自己的 API 密钥来查看你自己的数据。它是边看边做边学的形式。
它也有一些缺陷:
- 没有太多的空间来描述后端详细的工作
- 每个 Swagger UI 的输出看起来都差不多
- Swagger UI 会从你其他的文档中分离成独立的一个站点
创建 Swagger UI 展示
本节我们将为使用Mashape Weather API的 weatherdata 后台来创建一个 Swagger UI (weatherdata是之前的课程中创建的一个项目)。你可以在这里查看demo。
a.创建一个 Swagger spec 文件
1、去Swagger online editor
2、选择 File > Open Example 然后选择 PetStore Simple 。单击 Open。
你可以使用 weatherdata 后台文档来自定义这个示例 YML 文件。但如果你是新手, 它会带你认识spec。方便起见,只需要用到下面的文件,然后复制一份到 Swagger editor: swagger.yaml。
swagger: "2.0"
info:
version: "1.0.0"
title: "Weather API"
description: "A sample API that uses a Mashape weather API as an example to demonstrate features in the swagger-2.0 specification"
termsOfService: "http://helloreverb.com/terms/"
contact:
name: "Tom Johnson"
email: "tomjohnson1492@gmail.com"
url: "http://swagger.io"
license:
name: "MIT"
url: "http://opensource.org/licenses/MIT"
host: "simple-weather.p.mashape.com"
schemes:
- "https"
consumes:
- "application/json"
produces:
- "application/text"
paths:
/aqi:
get:
tags:
- "Air Quality"
description: "gets air quality index"
operationId: "getAqi"
produces:
- "text"
parameters:
-
name: "lat"
in: "query"
description: "latitude"
required: false
type: "string"
-
name: "lng"
in: "query"
description: "longitude"
required: false
type: "string"
responses:
200:
description: "aqi response"
default:
description: "unexpected error"
/weather:
get:
tags:
- "Weather Forecast"
description: "gets weather forecast in short label"
operationId: "getWeather"
produces:
- "text"
parameters:
-
name: "lat"
in: "query"
description: "latitude"
required: false
type: "string"
-
name: "lng"
in: