博客

PHP使用Swagger生成好看的API文档

  • Post category:PHP

以下是“PHP使用Swagger生成好看的API文档”的完整使用攻略，包括安装Swagger、编写Swagger注释、生成API文档等内容。

安装Swagger

要使用Swagger生成API文档，您需要先安装Swagger。您可以使用Composer来安装Swagger。以下是一个示例，演示如何使用Composer安装Swagger：

composer require zircote/swagger-php

编写Swagger注释

在PHP代码中编写Swagger注释，您可以使用Swagger提供的注释标签。以下是一个示例，演示如何在PHP代码中编写Swagger注释：

/**
 * @OA\Get(
 *     path="/users",
 *     summary="获取用户列表",
 *     @OA\Response(response="200", description="获取成功"),
 *     @OA\Response(response="401", description="未授权"),
 *     @OA\Response(response="403", description="禁止访问"),
 *     @OA\Response(response="404", description="未找到资源"),
 *     @OA\Response(response="500", description="服务器错误")
 * )
 */
public function getUsers()
{
    // 获取用户列表的代码
}

在上述示例中，我们使用@OA\Get注释标签来指定HTTP请求方法为GET，使用path属性来指定API路径为/users，使用summary属性来指定API的简要描述，使用@OA\Response注释标签来指定API的响应。您可以根据需要添加更多的注释标签来描述API的参数、请求体等信息。

生成API文档

在PHP代码中编写Swagger注释后，您可以使用Swagger提供的命令行工具来生成API文档。以下是一个示例，演示如何使用Swagger命令行工具来生成API文档：

vendor/bin/openapi --output public/swagger.json app/Http/Controllers

在上述示例中，我们使用vendor/bin/openapi命令来生成API文档，使用--output选项来指定输出文件为public/swagger.json，使用app/Http/Controllers参数来指定需要扫描的PHP文件所在的目录。

生成API文档后，您可以使用Swagger UI来将该文件渲染为一个漂亮的API文档。以下是一个示例，演示如何使用Swagger UI来渲染API文档：

<!DOCTYPE html>
<html>
<head>
    <title>API文档</title>
    <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.1/swagger-ui.min.css" />
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.1/swagger-ui-bundle.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.1/swagger-ui-standalone-preset.min.js"></script>
    <script>
        window.onload = function() {
            const ui = SwaggerUIBundle({
                url: "/swagger.json",
                dom_id: '#swagger-ui',
                presets: [
                    SwaggerUIBundle.presets.apis,
                    SwaggerUIStandalonePreset
                ],
                layout: "BaseLayout",
                deepLinking: true,
                showExtensions: true,
                showCommonExtensions: true
            });
        }
    </script>
</body>
</html>

在上述示例中，我们使用url属性来指定API文档的URL为/swagger.json，使用dom_id属性来指定Swagger UI的DOM元素ID为#swagger-ui，使用presets属性来指定Swagger UI的预设选项，使用layout属性来指定Swagger UI的布局，使用deepLinking属性来启用深度链接，使用showExtensions属性来显示Swagger扩展，使用showCommonExtensions属性来显示常用扩展。

将上述代码保存为index.html文件，然后将swagger.json文件和index.html文件放在同一个目录下。现在，您可以使用浏览器打开index.html文件，查看生成的漂亮的API文档了。

现在，您已经成功地学习了如何使用Swagger生成好看的API文档，包括安装Swagger、编写Swagger注释和生成API文档。

Tags: