如何使用 Laravel 集成 Swagger 文档

Swagger 是一种流行的 RESTful API 文档规范，它定义了一组描述 API 的标记语言。Laravel 一直以来就是以扩展性著称，我在本文中将介绍如何将 Swagger 集成到 Laravel 应用程序中。

Swagger-php 对比 L5-Swagger

社区有着大量的 Swagger 的工具，其中最被广泛使用的主要是: Swagger-php 和 L5-Swagger。

Swagger-php 是一个 PHP 库，用于将 Swagger 规范应用于 PHP 应用程序，自动生成 API 文档和客户端 SDK。它允许 PHP 开发人员通过注释代码来定义 API 的各个方面，包括端点、参数、响应和错误。Swagger-php 还提供了一个 UI，使得文档可以以交互式的方式浏览和测试。

L5-Swagger 是 Laravel 的一个插件，它基于 Swagger-php 和 Swagger-UI 而特意为 Laravel 定制的 Swagger 工具。咱们就从使用 L5-Swagger 开始上手，后面我们再了解 Swagger-php 的注解的写法。

手把手教你使用 L5-Swagger

Step 1. 使用 composer 添加该包

composer require darkaonline/l5-swagger

生成配置文件到 config 目录，可以自行去看看其中配置项

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

Step 2. 运行服务

php artisan serve

Laravel development server started: http://127.0.0.1:8000

Step 3. 浏览器访问

浏览器打开：http://127.0.0.1:8000/api/documentation

这样我们就得到一个 Swagger UI 的链接，是不是很方便。

Swagger-php 的注解示例

这是因为在 PHP 中，没有类似于 Java 或 Python 等语言的反射机制，无法自动获取代码中的注释信息。因此，Swagger-php 通过使用注解来显式地定义 API 的元数据信息。

使用注解可以使代码更加清晰易懂，而且可以与其他 PHP 框架和工具无缝集成。在 Swagger-php 中，通过添加特定的注解，开发人员可以指定 API 的各种元数据信息，包括请求和响应的数据类型、HTTP 方法、参数和路径等。这些注解可以被 Swagger-php 解析并转换为文档，以便于 API 的使用和维护。

定义Entity

<?php

/**
 * @license Apache 2.0
 */

namespace OpenApi\Examples\Petstore30\Models;

use OpenApi\Annotations as OA;

/**
 * Class Pet.
 *
 * @author  Donii Sergii <doniysa@gmail.com>
 *
 * @OA\Schema(
 *     description="Pet model",
 *     title="Pet model",
 *     required={"name", "photoUrls"},
 *     @OA\Xml(
 *         name="Pet"
 *     )
 * )
 */
class Pet
{
    /**
     * @OA\Property(
     *     format="int64",
     *     description="ID",
     *     title="ID",
     * )
     *
     * @var int
     */
    private $id;

    /**
     * @OA\Property(
     *     title="Category",
     * )
     *
     * @var Category
     */
    private $category;

    /**
     * @OA\Property(
     *     format="int64",
     *     description="Pet name",
     *     title="Pet name",
     * )
     *
     * @var int
     */
    private $name;

    /**
     * @OA\Property(
     *     description="Photo urls",
     *     title="Photo urls",
     *     @OA\Xml(
     *         name="photoUrl",
     *         wrapped=true
     *     ),
     *     @OA\Items(
     *         type="string",
     *         default="images/image-1.png"
     *     )
     * )
     *
     * @var array
     */
    private $photoUrls;

    /**
     * @OA\Property(
     *     description="Pet tags",
     *     title="Pet tags",
     *     @OA\Xml(
     *         name="tag",
     *         wrapped=true
     *     ),
     * )
     *
     * @var Tag[]
     */
    private $tags;
}

定义Controller

<?php

/**
 * @license Apache 2.0
 */

namespace OpenApi\Examples\Petstore30\Controllers;

use OpenApi\Annotations as OA;

/**
 * Class Pet.
 *
 * @author  Donii Sergii <doniysa@gmail.com>
 */
class Pet
{
    /**
     * Add a new pet to the store.
     *
     * @OA\Post(
     *     path="/pet",
     *     tags={"pet"},
     *     operationId="addPet",
     *     @OA\Response(
     *         response=405,
     *         description="Invalid input"
     *     ),
     *     security={
     *         {"petstore_auth": {"write:pets", "read:pets"}}
     *     },
     *     @OA\RequestBody(ref="#/components/requestBodies/Pet")
     * )
     */
    public function addPet()
    {
    }

    /**
     * Update an existing pet.
     *
     * @OA\Put(
     *     path="/pet",
     *     tags={"pet"},
     *     operationId="updatePet",
     *     @OA\Response(
     *         response=400,
     *         description="Invalid ID supplied"
     *     ),
     *     @OA\Response(
     *         response=404,
     *         description="Pet not found"
     *     ),
     *     @OA\Response(
     *         response=405,
     *         description="Validation exception"
     *     ),
     *     security={
     *         {"petstore_auth": {"write:pets", "read:pets"}}
     *     },
     *     @OA\RequestBody(ref="#/components/requestBodies/Pet")
     * )
     */
    public function updatePet()
    {
    }

生成 API 文档

编写完上面的注释，运行此命名：

php artisan l5-swagger:generate

Swagger-php 的主要注解

最后我再分别列举下咱们 Phper 写 Swagger 的常用注解。

@OA\Info 声明API版本信息

字段名称	类型	描述
version	string	需要 Api版本信息。
title	string	需要 API的标题。
description	string	参数的简要说明。
termsOfService	string	API的服务条款。
contact	联系对象	API的联系信息。
license	许可对象	API的许可证信息。

 /**
 * @OA\Info(
 *      version="1.0.0",
 *      title="服务端API",
 *      description="服务端API",
 *      termsOfService="http://example.com/terms/",
 *      @OA\Contact(
 *          url="http://www.example.com/support"
 *          email="miy@126.com",
 *          name="开发支持"
 *      ),
 *     @OA\License(
 *         name="Apache 2.0",
 *         url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *     )
 * )
 */

@OA\Server 服务器信息

字段名称	类型	描述
url	string	Api服务器地址，。
description	string	Api服务器描述。
variables	string	联系人/组织的邮箱。

/**
 *  @OA\Server(
 *      url=L5_SWAGGER_CONST_HOST,
 *      description="L5 Swagger OpenApi dynamic host server"
 *  )
 *
 *  @OA\Server(
*      url="https://projects.dev/api/v1",
 *      description="L5 Swagger OpenApi Server"
 * )
 */

@OA\Post、Get、Put、Delete 参数

tags	boolean	接口名称。
path	string	需要。接口请求地址。
summary	string	接口简短描述，Ui界面在path后面展示，这个字段应该少于120个字符，对接友好
description	string	接口详情描述，接口展开描述接口功能或样例。
operationId	string	友好的操作描述名称，Id在api操作描述中名称唯一，工具库可以使用这个Id标识唯一的操作
security	安全对象	注明该请求使用哪些安全策略：值列表描述了可以使用的替代安全方案（也就是说，安全需求之间存在逻辑或）。该定义覆盖任何已声明的顶层security。要删除顶级安全声明，可以使用空数组。
parameters	参数对象	适用于此操作的参数列表。如果在路径项目中已经定义了一个参数，新的定义将覆盖它，但是不能删除它。该列表不得包含重复的参数。一个独特的参数是由一个名称和位置的组合来定义的。该列表可以使用引用对象链接到在Swagger对象参数中定义的参数(如果参数巨多可以使用ref引入params对象)。最多可以有一个“body”参数。
responses	响应对象	需要。执行此操作时返回的可能响应列表。
schemes	string	操作的传输协议。值必须是从列表：“http”，“https”，“ws”，“wss”。该值将覆盖Swagger对象schemes定义。
deprecated	boolean	声明此操作将被弃用。宣布的操作的使用应该被禁止。默认值是false。
produces	string	操作可以产生的类型列表。这将覆盖producesSwagger对象的定义。可以使用空值清除全局定义。值必须如MIME类型下所述
consumes	string	该操作可以使用的类型列表。这将覆盖consumesSwagger对象的定义。可以使用空值清除全局定义。值必须如MIME类型下所述。
externalDocs	外部文档对象	有关此操作的其他外部文档。

/**
 * 
 * @OA\Get(
 *      path="/users",
 *      operationId="getListOfUsers",
 *      tags={"Users"},
 *      description="Get list of users",
 *      security={{"Authorization-Bearer":{}}}, 
 *      @OA\Parameter(
 *         name="Authorization",
 *         in="header",
 *         required=true,
 *         description="Bearer {access-token}",
 *         @OA\Schema(
 *              type="bearerAuth"
 *         ) 
 *      ), 
 *      @OA\Response(
 *          response=200,
 *          description="Get list of users.",
 *          @OA\JsonContent(type="object",
 *              @OA\Property(property="message", type="string"),
 *              @OA\Property(property="data", type="array",
 *                  @OA\Items(type="object",
 *                      @OA\Property(property="id", type="integer"),
 *                      @OA\Property(property="name", type="string"),
 *                      @OA\Property(property="email", type="string"),
 *                  ),
 *              ),
 *          ),
 *       ),
 *       @OA\Response(response=401, description="Unauthorized"),
 *       @OA\Response(response=404, description="Not Found"),
 * )
 * 
 *
 */

@OA\Response 参数描述

字段名称	类型	描述
description	string	必填响应的简短描述。。
schema	模式对象	响应结构的定义。它可以是一个基元，一个数组或一个对象。如果此字段不存在，则表示没有内容作为响应的一部分返回。
headers	标题对象	与响应一起发送的标题列表。
examples	示例对象	响应消息的一个例子。

    /*
     * @OA\Response(
     *          response=200,
     *          description="successful operation",
     *          @OA\JsonContent(ref="#/components/schemas/MsgExport")
     *       )
     */

@OA\Schema 用来执行Scheme模版

/**
*定义可以复用的响应模板：
*
*  @OA\Schema(
*       schema="MsgExport",
*       required={"code","reason"},
*       @OA\Property(
*            property="code",
*            type="integer",
*            format="int32",
*            description="状态码"
*       ),
*       @OA\Property(
*            property="reason",
*            type="string",
*            description="提示消息"
*            ),
*       @OA\Property(
*            property="result",
*            type="array",
*            description="请求结果",
*            @OA\Items(
*                 @OA\Property(
*                      property="id",
*                      type="integer",
*                      description="ID"
*                  ),
*            )
*       ),
*       @OA\Property(
*            property="params",
*            type="array",
*            description="其他二外参数",
*       ),
* ),
*
*定义手机验证码登录属性模板：
*@OA\Schema(
*      description:"短信验证码登录属性",
*      schema="MobileLogin",
*      required={"mobile", "code","codeType"},
*      example={"mobile":"18913556768","code":"123123","codeType":1},
*      @OA\Property(
*          property="mobile",
*          type="string",
*          description="手机号"
*      ),
*      @OA\Property(
*          property="code",
*          type="string",
*          description="在验证码"
*      ),
*     @OA\Property(
*          property="codeType",
*          type="integer",
*          description="验证码类型",
*          default=1,
*      ),
* )
*/

更多注解

另一种选择

鉴于 PHP 的语言特性，在代码中书写 Swagger 注解可能并不方便，我之前推荐了小伙伴们使用了 Apifox，反馈都说非常简单易用。直接在 Apifox 设计 Schema 和接口再导出接口定义，有兴趣的同学打开 Apifox 网页版用起来。Apifox 被定位为一体化 API 协作平台，可以实现 API 文档、API 调试、API Mock、 API 自动化测试，提供了一种全面的 API 管理解决方案。

使用 Laravel 插件得到的 swagger 文件，可以同步 swagger.json 同步到 Apifox 项目中，然后设计测试套件，还能跟持续集成配合跑自动化用例，简直不能太方便。

知识扩展：