uderline/openapi-php-attributes

Automatically render your OpenApi 3 file describing your PHP API using attributes

2.1.0 2024-03-25 20:17 UTC

Requires

• php: >=8.1
• symfony/finder: ^6.0|^7.0
• symfony/http-foundation: ^6.0|^7.0
• symfony/string: ^6.2

Requires (Dev)

• phpunit/phpunit: ^10.2.2

MIT

• Joseph Martell

• php
• json
• api
• renderer
• attributes
• openapi
• api-rest
• openapi3
• php8

README

This CLI Tool is able to generate an OpenApi JSON file description according to PHP attributes contained in your files.

⚠️ Missing something ?

Just open an issue saying what's missing ! Feel free to open a PR but we recommend opening an issue beforehand.

Where to start ?

1 - Install the package openapi-php-attributes-generator with composer.

composer require uderline/openapi-php-attributes

2 - Describe your API by following this documentation: https://uderline.github.io/openapi-php-attributes/

3 - Generate the JSON file:

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

A new file called openapi.json has been generated !

Example

#[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;
}

Will generate

{
    "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"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}