全栈工程师开发手册 (作者:栾鹏)
架构系列文章
简介
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 文档就是 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 。
使用说明
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 时,报错信息为:
这很有可能就是跨域问题导致的。
这里,我们使用 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 界面。
docker部署 Swagger
如果你先上面的步骤过于麻烦,你可以直接选择使用docker部署
1)下载swagger-editor的容器
docker pull swaggerapi/swagger-editor
docker run -d -p 81:8080 swaggerapi/swagger-editor
81:8080 将容器的8080端口暴露给localhost的81端口,在浏览中输入:http://127.0.0.1:81,就可以在容器中编辑api文档
编辑后,在页面上上方点击 File -> Download JSON,将文件下载到本地 命名为swagger.json
save as yaml可以保存api文件为openapi.yaml
2)下载swagger-ui的容器
docker pull swaggerapi/swagger-ui
3)配置文件挂在到容器中
docker run -d -p 80:8080 -v $(pwd):/usr/share/nginx/html/config swaggerapi/swagger-ui
-v:将当前目录挂在到 /usr/share/nginx/html/config中执行
没有将swagger.json或者openapi.yaml 在容器内修改的好处:在外部修改后容器可以直接运行,如果在容器内容修改需要在compile一次生成新的容器,这就复杂了哈
镜像的cmd,我们可以通过docker inspect <container id>
查看为
sh /usr/share/nginx/docker-run.sh
进入容器来进行一些修改
docker exec -it 5d214723fe37 /bin/sh
进入配置文件的根目录
cd /usr/share/nginx
配置文件都在这个目录下,配置json或yaml文件在
/usr/share/nginx/html/index.html文件的const ui = SwaggerUIBundle({…}) 行
设置url: “./config/swagger.json”,默认加载swagger.json为api文件。当然你也可以打开web网页后再输入./config/swagger.json 或者./config/openapi.yaml
4)web验证
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 的内容为:
<?phpnamespace 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', '*'); }}
服务器的接口地址为:http://apidemo.test/api/v1
现在,我们来编写 Swagger 文档。
我们使用docker安装的 Swagger-editor 来编写该文档。
浏览器访问http://127.0.0.1:81/,打开 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 文档。
pycharm编写swagger文档
下载pycharm的swagger的插件:https://plugins.jetbrains.com/plugin/8347-swagger
复制插件安装目录:把下载的插件复制到pycharm安装程序的plugins文件夹中。
提示重启pycharm,然后就可以直接创建swagger/openapi file