[译]5.41 Swagger tutorial
单击此处查看原文
关于 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: "query"
description: "longitude"