Swagger入门教程
关于 Swagger
Swagger能成为最受欢迎的REST APIs文档生成工具之一，有如下几个缘由：html
- Swagger 能够生成一个具备互动性的API控制台，开发者能够用来快速学习和尝试API。
- Swagger 能够生成客户端SDK代码用于各类不一样的平台上的实现。
- Swagger 文件能够在许多不一样的平台上从代码注释中自动生成。
- Swagger 有一个强大的社区，里面有许多强悍的贡献者。
Swagger 文档提供了一个方法，使咱们能够用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了好比 names、order 等 API 信息。git
你能够经过一个文本编辑器来编辑 Swagger 文件，或者你也能够从你的代码注释中自动生成。各类工具均可以使用 Swagger 文件来生成互动的 API 文档。github
注意：用 Swagger 文件生成互动的 API 文档是最精简的，它展现了资源、参数、请求、响应。可是它不会提供你的API如何工做的其余任何一个细节。web
Petstore 的 Swagger 例子
为了更好的理解 Swagger ，咱们如今来探索一下 Petsotre 项目的例子。记住：如下出现的 UI 都是指Swagger UI。Swagger 能够被展现成不一样的视觉样式，这取决于你所使用到的视觉框架。数据库
有三个资源：pet，store，user。apache
建立一个 pet
一、展开 pet 的 post 方法
二、而后单击 Model Schema 中的黄色字体的 JSON。json
这里用 JSON 填充了 body value。这里的 JSON 是你必须上传的，用于建立 pet 资源。后端
三、将第一个 id 标签的值修改一下（你必须保证 id 值都是惟一的，而且不能从 0 开始）。api
四、将 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"