README

这个命令行工具能够根据您文件中包含的PHP属性生成OpenApi JSON文件描述。

⚠️ 缺少什么？

只需创建一个问题说明缺少的内容！请随意创建一个PR，但我们建议先创建一个问题。

从哪里开始？

1 - 使用composer安装openapi-php-attributes-generator包。

composer require uderline/openapi-php-attributes

2 - 按照以下文档描述您的API： https://uderline.github.io/openapi-php-attributes/

3 - 生成JSON文件

php ./vendor/bin/opag /src/files/project openapi.json

已生成一个名为 openapi.json 的新文件！

示例

#[Controller]
class Controller {
    #[
        GET("/path/{id}", ["Tag1", "Tag2"], "Description of the method"),
        Property(Type::STRING, "prop1", description: "Property description", enum: BackedEnum::class),
        Property(Type::INT, "prop2", example: 1),
        Property(Type::BOOLEAN, "prop3"),
        Property(Type::REF, "prop4", ref: RefSchema::class)
        Response(ref: SchemaName::class, description: "Response description")
    ]
    public function get(#[Parameter("Parameter description")] int $id): JsonResponse {
        // ...
    }
}

enum BackedEnum: string
{
    case VAL1: "val1";
    case VAL2: "val2";
}

#[
    Schema,
    Property(Type::STRING, "Property 1"),
    Property(Type::INT, "Property 2"),
]
class RefSchema
{
    public string $property1;
    public int $property2;
}

将生成

{
    "paths": {
        "/path/{id}": {
            "post": {
                "tags": [
                    "Tag1",
                    "Tag2"
                ],
                "summary": "Description of the method",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "Parameter description",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "prop1": {
                                        "type": "string",
                                        "description": "Property description",
                                        "enum": [
                                            "val1",
                                            "val2"
                                        ]
                                    },
                                    "prop2": {
                                        "type": "integer",
                                        "description": ""
                                    },
                                    "prop3": {
                                        "type": "boolean",
                                        "description": ""
                                    },
                                    "prop4": {
                                        "$ref": "#/components/schemas/RefSchema"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Response description",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DummyComponent"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}