全栈工程师开发手册（作者：栾鹏）
架构系列文章

简介

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.gitcd 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 时，报错信息为：

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

这里，我们使用 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验证

输入：http://127.0.0.1:80

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.0title: DEMO 项目 API 接口文档
servers:                                  # 这里写服务器的接口地址- url: 'http://apidemo.test/api/v1' description: 沙箱环境
tags:                                     # 这里写某类 API 的标签- name: articlesdescription: 文章相关 API- name: usersdescription: 用户相关 API
paths:                                    # 这里写具体的 API 的相关信息（API 名称、请求类型、摘要、请求参数、响应等/articles:get:tags:- articlessummary: 获取所有文章列表description: 用于获取所有文章列表responses:'200':description: 请求成功后返回的内容content:application/json:schema:type: arrayitems:$ref: '#/components/schemas/Article'  # 引用可复用的组件post:tags:- articlessummary: 创建新文章description: 描述信息parameters:- name: titlein: querydescription: 文章标题required: trueschema:type: string- name: bodyin: querydescription: 文章内容required: trueschema:type: stringresponses:'200':description: 请求成功后返回的内容content:application/json:schema:$ref: '#/components/schemas/Article''400':description: 请求失败'/articles/{id}':get:tags:- articlessummary: 获取单篇文章description: 用于获取指定的单篇文章parameters:- name: idin: pathdescription: 文章 IDrequired: trueschema:type: integerresponses:'200':description: 请求成功后返回的内容content:application/json:schema:$ref: '#/components/schemas/Article''400':description: 请求失败put:tags:- articlessummary: 更新单篇文章description: 描述信息parameters:- name: idin: pathdescription: 文章 IDrequired: trueschema:type: integer- name: titlein: querydescription: 文章标题required: trueschema:type: string- name: bodyin: querydescription: 文章内容required: trueschema:type: stringresponses:'200':description: 请求成功后返回的内容content:application/json:schema:$ref: '#/components/schemas/Article''400':description: 请求失败delete:security:                           # 使用局部的安全认证，只对某个具体的接口生效（需要在下面定义安全组件）- bearerAuth: []tags:- articlessummary: 删除单篇文章description: 描述信息parameters:- name: idin: pathdescription: 文章 IDrequired: trueschema:type: integer- name: Key                       # 自定义请求头的用法in: header                      schema:type: stringrequired: trueresponses:'200':description: 请求成功后返回的内容content:application/json:schema:$ref: '#/components/schemas/Success''400':description: 请求失败
components:                               # 这里定义可复用的组件（如：数据模型、安全体系等）schemas:Article:type: objectproperties:id:description: 主键IDtype: integerexample: 1title:description: 文章标题type: stringexample: Ea quibusdambody:description: 文章内容type: stringexample: Dolores vitae inventore sapiente esse aut...created_at:description: 创建时间type: stringexample: '2018-04-04 18:23:48'updated_at:description: 更新时间type: stringexample: '2018-04-04 18:23:48'Success:type: objectproperties:code:description: 响应编码type: integerexample: 0msg:description: 响应编码的说明type: stringexample: 成功securitySchemes:                        # 安全体系相关的组件bearerAuth:type: httpscheme: 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

swagger入门和实践（含docker部署swagger）相关推荐

Docker入门到实践 (一) docker简介与安装、常用命令讲解
Docker入门到实践 (一) docker简介与安装一.docker 介绍 Docker 是一个开源的应用容器引擎打包应用以及依赖包到一个可移植的镜像中,发布到任何机器上,实现虚拟化.容器是 ...
Prometheus 原理和实践，含docker部署Prometheus、node Exporters、Alertmanager、Push Gateway、grafana
全栈工程师开发手册 (作者:栾鹏) 架构系列文章 Prometheus 入门与实践 2018 年 5 月 30 日发布随着容器技术的迅速发展,Kubernetes 已然成为大家追捧的容器集群管理系统. ...
史上最简单的docker入门到放弃——(利用docker部署web应用)
目录 @[TOC](目录) 第一章什么是docker 1.1 docker的发展史 1.2 docker国内应用史 1.3 什么是Docker 第二章了解docker 2.1 docker思想 2 ...
Spring Cloud开发实践 - 04 - Docker部署
Docker的安装和命令可以参考 https://www.cnblogs.com/milton/p/9866963.html . 资源规划这一步要区分传统资源和Docker资源, 为后面的细节定好基 ...
MongoDB从入门到实践（Docker安装及整合SpringBoot）
MongoDB 安装 docker run \ --name mongodb_server \ -p 27017:27017 \ -v /mongodb/single/conf/:/single/co ...
Windows下部署Swagger Edit、Swagger UI
Windows下部署Swagger Edit.Swagger UI 一.环境需求--已安装node环境二.准备Swagger Editor.Swagger UI源码三.搭建Swagger Edit ...
前端的Docker入门与实践
前端的Docker入门与实践感谢 & 参考本文内容还是相对很浅的,Docker中关于分布式,集群的内容没有涉及,所以本文推荐前端同学看一看,后端同学就不推荐了.本文中所有命令都是针对Ubu ...
Docker部署SDN环境
2014-12-03 by muzi Docker image = Java class Docker container = Java object 前言 5月份的时候,当我还是一个大学生的时候,有 ...
Docker -- 2 -- 利用docker部署网站和数据库
在Docker – 系统整洁之道 – 1中已经对Docker的一些命令和Docker镜像的使用及操作做了记录. 这次就利用docker进行一次真正的实例使用,使用docker搭建一个简单的答题系统,这 ...

swagger入门和实践（含docker部署swagger）

简介