如何使用 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版本信息

 /**
 * @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 服务器信息

/**
 *  @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 参数

/**
 * 
 * @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 参数描述

    /*
     * @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 项目中，然后设计测试套件，还能跟持续集成配合跑自动化用例，简直不能太方便。

知识扩展：

• 如何使用 Swagger Editor 编写 API 文档
• 写给全栈工程师的 Swagger 基础教程