Swagger 入门和实战

阳光穿透心脏的1/2处 2022-05-26 08:05 155阅读 0赞

## 简介 ##

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/][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.10.1_3001]
 *  [http://192.168.1.2:3001][http_192.168.1.2_3001]
 *  [http://127.0.0.1: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][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][https_blog.csdn.net_lamp_yang_3533_article_details_79944441] 。

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

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

### 更改默认的渲染文档 ###

Swagger-ui 默认渲染的是 [http://petstore.swagger.io/v2/swagger.json][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 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][http_apidemo.test_api_v1]

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

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

浏览器访问 [http://127.0.0.1:3001/][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 规范的详情，可参考[官方文档][Link 1] 。

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-php]: https://github.com/zircote/swagger-php
[https_swagger.io_docs]: https://swagger.io/docs/
[Swagger-editor]: http://editor.swagger.io/?&_ga=2.155992315.1324021563.1523554157-619122870.1523554157#/
[http_192.168.10.1_3001]: http://192.168.10.1:3001/
[http_192.168.1.2_3001]: http://192.168.1.2:3001/
[http_127.0.0.1_3001]: http://127.0.0.1:3001/
[https_github.com_swagger-api_swagger-ui]: https://github.com/swagger-api/swagger-ui
[https_blog.csdn.net_lamp_yang_3533_article_details_79944441]: https://blog.csdn.net/lamp_yang_3533/article/details/79944441
[https_swagger.io_docs_swagger-tools]: https://swagger.io/docs/swagger-tools/
[http_petstore.swagger.io_v2_swagger.json]: http://petstore.swagger.io/v2/swagger.json
[http_apidemo.test_api_v1]: http://apidemo.test/api/v1
[Link 1]: https://swagger.io/docs/specification/about/