Swagger入门教程

[译]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 是⽤于⽀持开发者使⽤ RESTAPI 的⼯具。

⼀些 Swagger 的实现例⼦

它们⼤多看起来⼀样。你会注意到 Swagger 实现的⽂档都很精简。这是因为 Swagger 的展⽰都是互动的体验，你可以尝试请求和查看响应，使⽤你⾃⼰的 API 密钥来查看你⾃⼰的数据。它是边看边做边学的形式。它也有⼀些缺陷：

没有太多的空间来描述后端详细的⼯作每个 Swagger UI 的输出看起来都差不多

Swagger UI 会从你其他的⽂档中分离成独⽴的⼀个站点

创建 Swagger UI 展⽰

本节我们将为使⽤的 weatherdata 后台来创建⼀个 Swagger UI （weatherdata是之前的课程中创建的⼀个项⽬）。你可以在这⾥查看。

a.创建⼀个 Swagger spec ⽂件

1、去

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\" 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 ⽂件也不能被正确解析）。3、保证 Swagger edirot 中的 YAML ⽂件有效。如果有错误必须要修正。

4、选择 File > Download YAML 并且保存为 swagger.yaml 到本地（你可以只复制代码然后粘贴到空⽩⽂件中，命名为 swagger.yaml）。你也可以选择 JSON 格式，不过 YAML 可读性更⾼。

b.设置 Swagger UI

1、Github: 。下载、解压。只需要⽤到 dist ⽂件夹。除⾮你想重新⽣成 dist 中的⽂件，才会⽤到别的。2、打开 dist > index.html

3、找到：url = \"http://petstore.swagger.io/v2/swagger.json\";4、值改成 swagger.yaml 的路径5、保存打开index.html

c.上传⽂件到 web 主机

除了本地浏览 Swagger ⽂件，你也可以使⽤ XAMPP 在本地运⾏⼀个 web 服务器1、下载安装

2、在你的应⽤程序⽂件夹中打开 XAMPP ⽂件夹，启动 manager-osx 控制台3、单击 Manage Servers tab

4、选择 Apache Web Server 单击 Start

5、打开 XAMPP 中的 htdocs ⽂件夹。如果是Mac，通常在 /Applications/XAMPP/xamppfiles/htdocs。6、将 dist ⽂件夹拖到此处

7、在你的浏览器中浏览 localhost/dist就可以看到 Swagger UI的展⽰。

体验 Swagger UI

1、⽤浏览器浏览 Swagger UI。

2、在右上⾓，单击 Authorize 并且输⼊你的 Mashape API Key。如果你没有 Mashape API Key，你可以3、使⽤EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p。4、去 Google Maps 搜索⼀个地址。

5、从 URL 中去获取经纬度，将其插⼊到你的 Swagger UI中（⽐如：1.33191 for lat, 103.7231246 for lng）6、单击 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 ⽂档块。其他⼯具参见