Swagger 入门和实战

admin管理员组

文章数量:1794759

Swagger 入门和实战

简介

Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。

Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。

Swagger 是一种通用的，和编程语言无关的 API 描述规范。

应用场景

• 如果你的 RESTful API 接口都开发完成了，你可以用 Swagger-editor 来编写 API 文档（ yaml 文件 或 json 文件），然后通过 Swagger-ui 来渲染该文件，以非常美观的形式将你的 API 文档，展现给你的团队或者客户。

• 如果你的 RESTful API 还未开始，也可以使用 Swagger 生态，来设计和规范你的 API，以 Annotation （注解）的方式给你的源代码添加额外的元数据。这样，Swagger 就可以检测到这些元数据，自动生成对应的 API 描述信。也就是说，Swagger 支持自动生成 API 文档。

Swagger 生态对 JAVA 的支持非常好，但对 PHP 的支持却略显不足。如果想要在 PHP 中自动生成 API 文档，可尝试使用 Swagger-php （目前仅兼容 Swagger 2.0 specification）。

规范

Swagger Specification（Swagger 规范），规定了如何对 API 的信进行正确描述。

Swagger 规范，以前称作 Swagger Specification，现在称作 OpenAPI Specification（简称 OAS）。

Swagger 规范学起来也不难，想熟练使用 Swagger 就必须熟悉 Swagger 规范。

Swagger 规范本身是与编程语言无关的，它支持两种语法风格：

• YAML 语法
• JSON 语法

这两种语法风格可以相互转换，都可以用来对我们的 RESTful API 接口的信进行准确描述，便于人类和机器阅读。

在 Swagger 中，用于描述 API 信的文档被称作 Swagger 文档。

Swagger 的规范主要有两种：

• Swagger 2.0
• OpenAPI 3.0

OpenAPI 3.0 规范是在 2017 年发布的，它在 Swagger 2.0 的基础上进行了优化，包括废弃某些关键词（host、basePath等），新增了一些关键词（servers、components、securitySchemes 等）。

OpenAPI 3.0 比 Swagger 2.0 更强大，使用起来更加灵活、方便。推荐使用 OpenAPI 3.0 。

关于 Swagger 规范的详细信，请参考官方文档 swagger.io/docs/ 。

Swagger 文档

Swagger 文档（文件），指的是符合 Swagger 规范的文件，用于对 API 的信进行完整地描述。

Swagger 文档是整个 Swagger 生态的核心。

Swagger 文档的类型有两种：yaml 文件和 json 文件。

yaml 文件用的是 YAML 语法风格；json 文件用的是 JSON 语法风格。这两种文件都可以用来描述 API 的信，且可以相互转换。

Swagger 文档（swagger.json 或 swagger.yaml）中关于 API 的描述必须符合 Swagger 规范，Swagger 文档是整个 Swagger 生态的核心。

简单的说，Swagger 文档就是 API 文档，只不过 Swagger 文档是用特定的语法来编写的。Swagger 文档本身看起来并不美观，这时，就需要一个好的 UI 工具将其渲染一番，这个工具就是 Swagger-ui。

我们可以用任何编辑器来编写 Swagger 文档，但为了方便在编辑的同时，检测 Swagger 文档是否符合规范，就有了 Swagger-editor 编辑器。

工具

Swagger 生态主要包含以下几种工具：

• Swagger-editor 是一种编辑器，用于编写 Swagger 文档，还支持文档实时检测、API 调试等功能。
• Swagger-ui 是一种 UI 渲染工具，用于渲染 Swagger 文档，以提供美观的 API 界面。
• Swagger-codegen 是一种代码生成器，可基于 Swagger 文档，来构建服务器端 stub 和 客户端 SDK。

Swagger-editor

Swagger-editor 主要用于编写符合 Swagger 规范的 RESTful API 文档，即编写 Swagger 文档。

Swagger-editor 是一个编辑器，可编写 Swagger 文档，来准确描述 API 信。

Swagger-editor 可采用两种语法风格：

• YAML 语法
• JSON 语法

当然，不使用 Swagger-editor 也可以，你可以使用任何编辑器来编写 Swagger 文档。

Swagger-editor 的功能

• 编写 Swagger 文档
• 实时检测 Swagger 文档是否符合 Swagger 规范
• 调试 Swagger 文档里描述的 API 接口
• 转换 Swagger 文档（yaml 转 json，或 json 转 yaml）

可见，Swagger-editor 编辑器比一般的编辑器更适合编写 Swagger 文档。当然 Swagger-editor 的功能还不止上面这些。因此，推荐使用 Swagger-editor。

Swagger-editor 的安装和使用

Swagger-editor 有两种方式使用：

• Web 版本的 Swagger-editor
• 本地的 Swagger-editor

Web 版本的 Swagger-editor

Web 版本的 Swagger-editor 直接运行在公网上，Swagger 已经给我们配置好了在线的 Swagger-editor。

也就是说，我们可以直接在浏览器上，访问 Swagger-editor 的 Web 版本来使用它，而无需安装。

用法和本地安装的 Swagger-editor 一样，几乎没有区别。

本地的 Swagger-editor

当然，我们也可以不使用 Web 版本的，而是选择自己在本地安装 Swagger-editor。

本地运行 Swagger-editor，需要 Node.js 环境支持。

请确保你的电脑已经安装了 Node.js 。

本地安装方法如下：

git clone github/swagger-api/swagger-editor.git cd swagger-editor npm install npm run build npm start

注：npm start 命令的作用是在本地启动 http-server，也就是一个 web 服务器。http-server 和 apache、nginx 一样，都是 web 服务器，只不过 http-server 是 Node.js 的内置模块。

推荐单独安装 Swagger-editor。安装完成后，以后想要运行 Swagger-editor，只需切换到 Swagger-editor 的目录，执行下面的命令即可。

npm start

启动成功后，就可以通过以下三种方式的任意一种来访问本地安装的 Swagger-editor 。

• 192.168.10.1:3001
• 192.168.1.2:3001
• 127.0.0.1:3001

使用说明

Swagger-editor 分为菜单栏和主体界面两个部分。

Swagger-editor 的界面分为左右两栏，左侧是编辑区，右侧是显示区。

编辑区里默认有一个 Swagger 文档的样例，你可以将其清空，编写自己的 API 描述。

显示区是对应编辑区中的 Swagger 文档的 UI 渲染情况，也就是说，右侧显示区的结果和使用 Swagger-ui 渲染 Swagger 文档后的显示结果基本一致。

Swagger-editor 的菜单栏包含以下几个菜单：

• File： 用于导入、导出、转换、清空 Swagger 文档。
• Edit： 用于转换为标准的 YAML 格式文件，比如删除空白行等。
• Generate Server： 用于构建服务器端 stub 。
• Generate Client： 用于构建客户端 SDK 。

Swagger-ui

Swagger-ui 是一套 HTML/CSS/JS 框架，用于渲染 Swagger 文档，以便提供美观的 API 文档界面。

也就是说，Swagger-ui 是一个 UI 渲染工具。

安装和使用

到 github/swagger-api/swagger-ui 下载最新的 swagger-ui 。

git clone github/swagger-api/swagger-ui.git

下载完成后，单独部署到你自己的 Web 服务器即可。

swagger-ui/dist/index.html 文件是 swagger-ui 项目的入口文件，故你需要将 Web 服务器的根目录指向 swagger-ui/dist。

这种将 swagger-ui 单独部署为一个项目的做法，会产生跨域的问题。比如，你调试 API 时，报错信为：

TypeError: Cannot read property 'statusText' of undefined

这很有可能就是跨域问题导致的。

这里，我们使用 CORS（跨源资源共享）来解决跨域问题，这样的话，就只需改动服务器端代码，而无需改动客户端代码，而且 CORS 支持各种请求类型。

通过 CORS 来解决跨域问题的基本思路是在服务器端添加响应头：

Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS Access-Control-Allow-Headers: Content-Type, Key, Authorization

CORS 请求中的非简单请求会先发送一次预检请求（请求类型为 OPTIONS），再发送正式的请求。

为了防止非简单请求的两次请求产生重复操作的问题（比如同时添加了两篇文章），最好将预检请求的路由单独写。

在 Laravel 中，可以这样写：

Route::options('articles/{article?}', function () { // 预检请求单独写，否则，可能出现重复操作的问题 return response()->json([]) // 预检请求返回一个空数组即可 ->header('Access-Control-Allow-Origin', '*') ->header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS') ->header('Access-Control-Allow-Headers', 'Content-Type, Key, Authorization'); });

如果你对跨域请求还不明白，可参考 blog.csdn/lamp_yang_3533/article/details/79944441 。

当然，如果你不想跨域，就将 Swagger-ui 集成到你的 API 项目中。只需拷贝 Swagger-ui/dist 目录即可。

关于 Swagger-ui 的更多细节，请参考官网 swagger.io/docs/swagger-tools/ 。

更改默认的渲染文档

Swagger-ui 默认渲染的是 petstore.swagger.io/v2/swagger.json ， 它是官方提供的一个 Demo。

如果你已经编写好了自己的 Swagger 文档，可以进行更换。

只需修改 swagger-ui/dist/index.html 文件，将

url: "petstore.swagger.io/v2/swagger.json",

更改为

url: "openapi.yaml",

openapi.yaml 是我编写的 Swagger 文档，由于我已经将其拷贝到了 swagger-ui/dist 目录中，所以可以这么写。

然后，在浏览器中访问 Swagger-ui 项目，就可以看到你的 Swagger 文档被渲染后的 UI 界面。

Swagger 实战

由于时间关系，这里只演示通过 Swagger-editor 和 Swagger-ui，来给一个已经完成的 API 项目编写 API 文档。

现在，有一个 Laravel 5.5 写的 API 项目，其路由配置如下：

Route::prefix('v1')->group(function () { Route::get('articles', 'ArticleController@index'); // 获取所有文章列表 Route::get('articles/{article}', 'ArticleController@show'); // 获取单篇文章 Route::post('articles', 'ArticleController@store'); // 创建新文章 Route::put('articles/{article}', 'ArticleController@update'); // 更新文章 Route::delete('articles/{article}', 'ArticleController@delete');; // 删除文章 Route::options('articles/{article?}', function () { // 预检请求单独写，否则，可能出现重复操作的问题 return response()->json([]) // 预检请求返回一个空数组即可 ->header('Access-Control-Allow-Origin', '*') ->header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS') ->header('Access-Control-Allow-Headers', 'Key, Authorization'); }); });

apidemo/app/Http/Controllers/ArticleController.php 的内容为：

<?php namespace App\\Http\\Controllers; use App\\Article; use Illuminate\\Http\\Request; use App\\Http\\Resources\\ArticleResource; class ArticleController extends Controller { /** * 获取文章列表 */ public function index() { $data = Article::all(); return response()->json($data, 200) ->header('Access-Control-Allow-Origin', '*'); } /** * 获取文章的单条记录 */ public function show(Request $request, Article $article) { // ArticleResource::withoutWrapping(); // return new ArticleResource($article); return response()->json($article, 200) ->header('Access-Control-Allow-Origin', '*'); } /** * 创建新文章 */ public function store(Request $request) { $article = Article::create($request->all()); return response()->json($article, 200) ->header('Access-Control-Allow-Origin', '*'); } /** * 更新文章 */ public function update(Request $request, Article $article) { $article->update($request->all()); return response()->json($article, 200) ->header('Access-Control-Allow-Origin', '*'); } /** * 删除文章 */ public function delete(Request $request, Article $article) { $article->delete(); $headers['key'] = $request->header('key'); $headers['authorization'] = $request->header('Authorization'); return response()->json(['code'=>0, 'msg' => '删除成功', 'header'=>$headers], 200) ->header('Access-Control-Allow-Origin', '*'); } }

服务器的接口地址为：apidemo.test/api/v1

现在，我们来编写 Swagger 文档。

我们使用本地安装的 Swagger-editor 来编写该文档。

浏览器访问 127.0.0.1:3001/ ，打开 Swagger-editor 编辑器。

点击菜单栏的 File → Clear Editor，来清空编辑区里默认的 Demo 内容。

然后，一步一步编写出我们的代码，用于描述我们的 API 。

openapi: 3.0.0 info: description: 这里是接口文档的描述信 version: 1.0.0 title: DEMO 项目 API 接口文档 servers: # 这里写服务器的接口地址 - url: 'apidemo.test/api/v1' description: 沙箱环境 tags: # 这里写某类 API 的标签 - name: articles description: 文章相关 API - name: users description: 用户相关 API paths: # 这里写具体的 API 的相关信（API 名称、请求类型、摘要、请求参数、响应等 /articles: get: tags: - articles summary: 获取所有文章列表 description: 用于获取所有文章列表 responses: '200': description: 请求成功后返回的内容 content: application/json: schema: type: array items: $ref: '#/components/schemas/Article' # 引用可复用的组件 post: tags: - articles summary: 创建新文章 description: 描述信 parameters: - name: title in: query description: 文章标题 required: true schema: type: string - name: body in: query description: 文章内容 required: true schema: type: string responses: '200': description: 请求成功后返回的内容 content: application/json: schema: $ref: '#/components/schemas/Article' '400': description: 请求失败 '/articles/{id}': get: tags: - articles summary: 获取单篇文章 description: 用于获取指定的单篇文章 parameters: - name: id in: path description: 文章 ID required: true schema: type: integer responses: '200': description: 请求成功后返回的内容 content: application/json: schema: $ref: '#/components/schemas/Article' '400': description: 请求失败 put: tags: - articles summary: 更新单篇文章 description: 描述信 parameters: - name: id in: path description: 文章 ID required: true schema: type: integer - name: title in: query description: 文章标题 required: true schema: type: string - name: body in: query description: 文章内容 required: true schema: type: string responses: '200': description: 请求成功后返回的内容 content: application/json: schema: $ref: '#/components/schemas/Article' '400': description: 请求失败 delete: security: # 使用局部的安全认证，只对某个具体的接口生效（需要在下面定义安全组件） - bearerAuth: [] tags: - articles summary: 删除单篇文章 description: 描述信 parameters: - name: id in: path description: 文章 ID required: true schema: type: integer - name: Key # 自定义请求头的用法 in: header schema: type: string required: true responses: '200': description: 请求成功后返回的内容 content: application/json: schema: $ref: '#/components/schemas/Success' '400': description: 请求失败 components: # 这里定义可复用的组件（如：数据模型、安全体系等） schemas: Article: type: object properties: id: description: 主键ID type: integer example: 1 title: description: 文章标题 type: string example: Ea quibusdam body: description: 文章内容 type: string example: Dolores vitae inventore sapiente esse aut... created_at: description: 创建时间 type: string example: '2018-04-04 18:23:48' updated_at: description: 更新时间 type: string example: '2018-04-04 18:23:48' Success: type: object properties: code: description: 响应编码 type: integer example: 0 msg: description: 响应编码的说明 type: string example: 成功 securitySchemes: # 安全体系相关的组件 bearerAuth: type: http scheme: bearer

可以发现，这里我们使用的 Swagger 规范是 openapi 3.0.0，而且用的是 yaml 语法风格。

关于 Swagger 规范的详情，可参考官方文档 。

yaml 的语法：

• yaml 同 json、xml 一样，也可以用来表示复杂结构的数据
• yaml 严格区分大小写
• 使用缩进来表示数据之间的层级关系，缩进应该采用空格键，而不是 tab 键
• 使用 # 号表示注释
• 键值对的 map 结构用 : 表示
• 列表数据（相当于索引数组），用 - 表示
• 字符串不需要用双引号标注

编写好 Swagger 文档后，点击 Swagger-editor 菜单栏里的 File → Save as YAML，浏览器会自动将编辑区里的内容下载到本地文件，文件名为 openapi.yaml 。

openapi.yaml 文件就是我们常说的 Swagger 文档，它是 Swagger 生态的核心。

最后，我们修改 Swagger-ui 项目的默认渲染文档即可。

只需修改 swagger-ui/dist/index.html 文件，将

url: "petstore.swagger.io/v2/swagger.json",

更改为

url: "openapi.yaml",

在浏览器中，访问你的 Swagger-ui 项目，就可以以非常美观的形式展示你的 API 文档。

本文标签： 实战入门Swagger