Swagger-php 中使用属性定义 API 的完整指南

2024-03-28 01:23:12

使用属性在 Swagger-php 中定义 API 的指南

简介

在 RESTful API 开发中， API 以便于文档和测试至关重要。Swagger 是一个流行的规范，用于使用 OpenAPI JSON 格式定义 API。Swagger-php 是一个库，可帮助使用 PHP 创建 OpenAPI 文档。本指南将介绍如何使用属性在 Swagger-php 中定义 API。

使用属性定义 API

Swagger-php 3.0 及更高版本支持使用属性来定义 API，这是一种简化 OpenAPI 定义的方法，尤其是在使用 PHP 8 或更高版本时。使用以下属性：

@OA\Schema: 定义 API 模型
@OA\Property: 定义模型中的属性
@OA\Parameter: 定义函数或方法的参数
@OA\Response: 定义函数或方法的响应

例如，以下代码使用属性定义一个名为 "Product" 的 API 模型：

/**
 * @OA\Schema(
 *     title="Product",
 *     description="A product in the store",
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="name", type="string"),
 *     @OA\Property(property="price", type="number")
 * )
 */
class Product
{
    public int $id;
    public string $name;
    public float $price;
}

生成 OpenAPI 文档

使用属性定义 API 后，可以通过 Swagger-php 的 OpenApi 类生成 OpenAPI 文档：

use OpenApi\Generator;

$openapi = Generator::scan([Product::class]);
$openapi->dump(); // 打印 OpenAPI 文档

生成 Swagger UI

Swagger UI 是一个查看和测试 OpenAPI 文档的工具。可以使用 Swagger-php 的 SwaggerUi 类生成 Swagger UI：

use OpenApi\Generator;
use OpenApi\UI\SwaggerUi;

$openapi = Generator::scan([Product::class]);
$swaggerUi = new SwaggerUi($openapi);
$swaggerUi->generate(); // 生成 Swagger UI HTML