简介

2023-09-06 22:44:19

ThinkPHP SwaggerV3 扩展包：揭开 API 文档化的新篇章

在如今 API 驱动的世界中，清晰且全面的文档对于确保 API 的可理解性和可维护性至关重要。SwaggerV3 作为 OpenAPI 规范的最新版本，提供了构建交互式、机器可读的 API 文档的标准化方法。为了简化 ThinkPHP 框架中 SwaggerV3 的集成，我们推出了一个功能强大的扩展包。

安装

在 ThinkPHP 根目录下运行以下命令创建扩展包：

composer create-project tp/think-swagger-v3

创建包

cd think-swagger-v3

安装扩展包依赖项：

composer install

注册扩展包：

// config/autoload.php
return [
    // ...
    'middleware' => [
        // ...
        'think\middleware\Swagger',
    ],
];

用例

在 ThinkPHP 控制器中使用以下注释来提取 API 端点的元数据：

/**
 * @SWG\Get(
 *     path="/articles",
 *     summary="获取文章列表",
 *     tags={"Articles"},
 *     @SWG\Response(
 *         response=200,
 *         description="成功获取文章列表",
 *         @SWG\Schema(
 *             type="array",
 *             @SWG\Items(
 *                 ref="#/definitions/Article"
 *             )
 *         )
 *     )
 * )
 */
public function index()
{
    // ...
}

在 ThinkPHP 模型中使用以下注释来提取模型元数据：

/**
 * @SWG\Definition(
 *     definition="Article",
 *     type="object",
 *     required={"title", "content"},
 *     @SWG\Property(
 *         property="id",
 *         type="integer",
 *         description="文章 ID"
 *     ),
 *     @SWG\Property(
 *         property="title",
 *         type="string",
 *         description="文章标题"
 *     ),
 *     @SWG\Property(
 *         property="content",
 *         type="string",
 *         description="文章内容"
 *     )
 * )
 */
class Article
{
    // ...
}