README

composer require amsify42/php-swagger-postman

要生成特定端点的属性，可以调用此方法

$attribute = new \Amsify42\PhpSwaggerPostman\Swagger\Attribute();
echo $attribute->generate();

您还可以通过键值对传递参数规则和路由参数，将其添加到属性中

echo $attribute->generate(
  ['name' => 'required', 'address_id' => 'reqiured|integer'],
  ['userId' => 42]
);

要生成属性中的响应数据

$attribute->setSuccessData(['id' => 42, 'name' => 'SomeUser']);
echo $attribute->generate();

您还可以传递回调函数来检查规则，并决定参数是否需要 TinyInt 或 Enum 值或自定义属性属性

$attribute->checkRules(
                function ($name, $rule) {
                    if ($rule == 'some_custom_rule') {
                        return [
                            'property' => // Pass some custom property attribute syntax
                        ];
                    } else if ($rule == 'enum') {
                        return  [
                            'enum' => ['paid', 'unpaid']
                        ];
                    } else if ($rule == 'boolean') {
                        return  [
                            'tinyint' => true
                        ];
                    }
                    return NULL;
                }
            );

默认情况下，如果 tinyint/enum/property 的数组未返回，则返回 NULL，如果您想为可能具有简单或嵌套数组的参数生成属性

$attribute->checkRules(
                function ($name, $rule) use($attribute) {
                    if ($rule == 'array') {
                        return [
                            'property' => $attribute->createObjectOrArrayProperty(
                                $_POST[$name], // or $_GET[$name] or value from body data
                                $name
                              )
                        ];
                    }
                    return NULL;
                }
            );

要添加安全

$attribute->setSecurity('XApiKey'); // The XApiKey will be from the security attribute already added

已添加示例安全属性

#[OA\SecurityScheme(
    securityScheme: "XApiKey",
    type: "apiKey",
    in: "header",
    name: "X-Api-Key"
)]

要添加具有静态值的头部

$attribute->setHeader(['Auth-Key' => 'some_key']);

要添加已定义的响应

$attribute->setResponse([
                [
                    'code' => 422,
                    'ref' => '#/components/responses/Validation' // Validation here is the name of response which is already defined somewhere
                ]
            ]);

示例验证已定义

#[OA\Response(
    response: "Validation",
    description: "Validation Errors",
    content: new OA\JsonContent(
        properties: [
            new OA\Property(
                property: "message",
                example: "Please check the inputs provided"
            ),
            new OA\Property(
                property: "errors",
                type: "object"
            )
        ]
    )
)]

要生成 注解 而不是 属性

$annotation = new \Amsify42\PhpSwaggerPostman\Swagger\Annotation();
echo $annotation->generate();

注意

1. 您可以使用上述所有 注解 方法，这些方法与 属性 相同，但 属性 需要 8.2 及以上版本的 PHP。
2. 要使用已安装的最新 swagger-php 中的注解，您可能需要单独安装 doctrine/annotations

composer require doctrine/annotations

有关更多详细信息，请参阅此链接 https://github.com/zircote/swagger-php/blob/master/docs/guide/migrating-to-v4.md

扫描目录并生成 API 文档和 postman 集合以及 postman 环境的 JSON。

$swagger = new \Amsify42\PhpSwaggerPostman\Swagger;
$swagger->getGeneratedJson(
    "path/to/scan-directory",
    "path/to/export-swagger-and-postman-json/"
);

注意

1. 确保在运行 $swagger->getGeneratedJson() 方法之前已添加 OA/Info 和至少一个 API 端点。
2. 为了在扫描目录时正确检测源类，可以在 composer.json 中设置 autoload 或使用 spl_autoload_register() 方法来自定义类的自动加载。

use OpenApi\Attributes as OA;

#[OA\Info(title: "My API", version: "1.0.0")]

#[OA\Get(path:"/api/users")]
#[OA\Response(response:"200", description:"An example endpoint")]

注解示例

/**
 * @OA\Info(
 *   version="1.0.0",
 *   title="My API"
 * )
 */

/**
 * @OA\Get(
 *     path="/api/users",
 *     @OA\Response(response="200", description="An example endpoint")
 * )
 */

如果要让 postman 环境包含 baseURL 变量的值，您可以像这样设置

$swagger = new \Amsify42\PhpSwaggerPostman\Swagger('http://www.site.com');
$swagger->getGeneratedJson(
    "path/to/scan-directory",
    "path/to/export-swagger-and-postman-json/"
);

或在属性中定义至少一个服务器

#[OA\Server(
    url: 'http://www.site.com',
    description: 'some description about site'
)]

或在注解中

/**
 * @OA\Server(
 *     url="http://www.site.com",
 *     description="some description about site"
 * )
 */

要添加 postman 环境文件名中的环境后缀，您可以在 Swagger 构造函数的第二个参数中传递它

$swagger = new \Amsify42\PhpSwaggerPostman\Swagger('http://www.site.com', 'Local');