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 规范的详细信息，请参考官方文档 https://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 https://github.com/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 。

• http://192.168.10.1:3001
• http://192.168.1.2:3001
• http://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 渲染工具。

安装和使用

到 https://github.com/swagger-api/swagger-ui 下载最新的 swagger-ui 。

git clone https://github.com/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');
});

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

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

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

更改默认的渲染文档

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

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

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

url: "http://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 AppHttpControllers;
use AppArticle;
use IlluminateHttpRequest;
use AppHttpResourcesArticleResource;
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', '*');
}
}

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

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

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

浏览器访问 http://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: 'http://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: "http://petstore.swagger.io/v2/swagger.json",

更改为

url: "openapi.yaml",

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

最后

以上就是眯眯眼白昼为你收集整理的Swagger 入门和实战的全部内容，希望文章能够帮你解决Swagger 入门和实战所遇到的程序开发问题。

如果觉得靠谱客网站的内容还不错，欢迎将靠谱客网站推荐给程序员好友。