[译]5.41 Swagger tutorial
单击此处查看原文
更多概念参见：Implementing Swagger with your API docshtml
关于 Swagger
Swagger能成为最受欢迎的REST APIs文档生成工具之一，有如下几个缘由：git
- Swagger 能够生成一个具备互动性的API控制台，开发者能够用来快速学习和尝试API。
- Swagger 能够生成客户端SDK代码用于各类不一样的平台上的实现。
- Swagger 文件能够在许多不一样的平台上从代码注释中自动生成。
- Swagger 有一个强大的社区，里面有许多强悍的贡献者。
Swagger 文档提供了一个方法，使咱们能够用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了好比 names、order 等 API 信息。github
你能够经过一个文本编辑器来编辑 Swagger 文件，或者你也能够从你的代码注释中自动生成。各类工具均可以使用 Swagger 文件来生成互动的 API 文档。web
注意：用 Swagger 文件生成互动的 API 文档是最精简的，它展现了资源、参数、请求、响应。可是它不会提供你的API如何工做的其余任何一个细节。数据库
Petstore 的 Swagger 例子
为了更好的理解 Swagger ，咱们如今来探索一下 Petsotre 项目的例子。记住：如下出现的 UI 都是指Swagger UI。Swagger 能够被展现成不一样的视觉样式，这取决于你所使用到的视觉框架。apache
有三个资源：pet，store，user。json
建立一个 pet
一、展开 pet 的 post 方法
二、而后单击 Model Schema 中的黄色字体的 JSON。后端
这里用 JSON 填充了 body value。这里的 JSON 是你必须上传的，用于建立 pet 资源。api
三、将第一个 id 标签的值修改一下（你必须保证 id 值都是惟一的，而且不能从 0 开始）。浏览器
四、将 name 标签的值修改一下（最好也要惟一，方便对比结果），如下是示例代码：
{
"id": 37987, "category": { "id": 0, "name": "string" }, "name": "Mr. Fluffernutter", "photoUrls": [ "string" ], "tags": [ { "id": 0, "name": "string" } ], "status": "available" }
五、单击 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 文件
一、去Swagger online editor
二、选择 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" required: false type: "string" responses: 200: description: "weather response" default: description: "unexpected error" /weatherdata: get: tags: - "Full Weather Data" description: "Get weather forecast by Latitude and Longitude" operationId: "getWeatherData" produces: - "application/json" parameters: - name: "lat" in: "query" description: "latitude" required: false type: "string" - name: "lng" in: "query" description: "longitude" required: false type: "string" responses: 200: description: "weatherdata response" default: description: "unexpected error" securityDefinitions: internalApiKey: type: apiKey in: header name: X-Mashape-Key
注意：使用 YML 替换JSON。 YML 句法比 JSON 可读性高。使用 YML ，空格很重要。新段落须要缩进两个空格。冒号表示个对象。连字符表明一个 sequence 或者 list （像一个 array）。若是你下载这个文件而不是复制粘贴，你基本不会碰到空格问题。
Swagger editor 告诉你文件如何被输出，你也能够看到验证出来的错误。没有这个在线编辑器，你只能在运行代码的时候才能知道 YML 句法是否有效 （而且看到错误提示， YAML 文件也不能被正确解析）。
三、保证 Swagger edirot 中的 YAML 文件有效。若是有错误必需要修正。
四、选择 File > Download YAML 而且保存为 swagger.yaml 到本地（你能够只复制代码而后粘贴到空白文件中，命名为 swagger.yaml）。
你也能够选择 JSON 格式，不过 YAML 可读性更高。
b.设置 Swagger UI
一、Github: Swagger UI。下载、解压。只须要用到 dist 文件夹。除非你想从新生成 dist 中的文件，才会用到别的。
二、打开 dist > index.html
三、找到：url = "http://petstore.swagger.io/v2/swagger.json";
四、值改为 swagger.yaml 的路径
五、保存打开index.html
c.上传文件到 web 主机
除了本地浏览 Swagger 文件，你也可使用 XAMPP 在本地运行一个 web 服务器
一、下载安装XAMPP
二、在你的应用程序文件夹中打开 XAMPP 文件夹，启动 manager-osx 控制台
三、单击 Manage Servers tab
四、选择 Apache Web Server 单击 Start
五、打开 XAMPP 中的 htdocs 文件夹。若是是Mac，一般在 /Applications/XAMPP/xamppfiles/htdocs。
六、将 dist 文件夹拖到此处
七、在你的浏览器中浏览 localhost/dist
就能够看到 Swagger UI的展现。
体验 Swagger UI
一、用浏览器浏览 Swagger UI。
二、在右上角，单击 Authorize 而且输入你的 Mashape API Key。若是你没有 Mashape API Key，你能够三、使用 EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p。
四、去 Google Maps 搜索一个地址。
五、从 URL 中去获取经纬度，将其插入到你的 Swagger UI中（好比：1.3319164 for lat, 103.7231246 for lng）
六、单击 Try it out。
若是成功，你应该能够看到 response body 的响应：9 c, Mostly Cloudy at South West, Singapore
若是你看到了Not supported，尝试调整经纬度。
若是你刷新了界面，你要从新输入 API Key。
从注释中自动生成 Swagger 文件
为了代替 Swagger file 的手动编码，你也能够从你的程序代码注释中自动生成。有许多的 Swagger 库能够用来整合不一样的代码库。这些 Swagger 库能够解析注释而且生成跟以前手动生成相同的 Swagger 文件。
要整合 Swagger 到本身的代码中，要容许开发者便捷的撰写文档，保证新特性都会被记录，而且保持文档的更新。这里是一个教程，使用 Swagger 为 Scalatra 从注释中自动生成文档.这些注释方法根据不一样的语言分红不一样的 Swagger 文档块。
其余工具参见 Swagger services and tools