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 的内容为：

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

现在，我们来编写 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 文档。