open-solid/open-api-bundle

Provides a tight integration of OpenApi into the Symfony full-stack framework

v0.1.0 2024-08-09 18:27 UTC

Requires

• php: >=8.2
• symfony/expression-language: ^7.0
• symfony/framework-bundle: ^7.0
• symfony/property-access: ^7.0
• symfony/serializer: ^7.0
• symfony/validator: ^7.0
• zircote/swagger-php: ^4.7

Requires (Dev)

• phpunit/phpunit: ^10.0
• psalm/plugin-phpunit: ^0.18
• roave/security-advisories: dev-latest
• symfony/browser-kit: ^7.0
• vimeo/psalm: ^5.0

Conflicts

• zircote/swagger-php: =4.8.7

MIT

• Yonel Ceruto

• symfony
• bundle
• swagger
• openapi

README

Provides a tight integration of the famous zircote/swagger-php library into the Symfony full-stack framework for generating OpenAPI spec and building Restful APIs quickly.

This bundle is especially created for API-First development.

Installation

composer require open-solid/open-api-bundle

Import the bundle's routes in config/routes.yaml to show the Swagger API documentation:

openapi:
    resource: '@OpenApiBundle/config/routes.php'

Basic Sample

Define your OpenAPI spec and endpoint at the same time:

<?php

namespace Api\Catalog\Controller\Post;

use Api\Catalog\Model\Product;
use OpenSolid\OpenApiBundle\Attribute\Payload;
use OpenSolid\OpenApiBundle\Routing\Attribute\Post;

class PostProductAction
{
    #[Post('/products')]
    public function __invoke(#[Payload] PostProductPayload $Payload): Product
    {
        return new Product($body->name, $Payload->price);
    }
}

Main Features

• Generate OpenAPI spec from PHP attributes (Mainly based on zircote/swagger-php)
  • Automatic Operation, Schema and Property guessing from PHP classes and methods
• Expose Swagger UI to explore the OpenAPI spec and test API endpoints
• Export OpenAPI spec in JSON or YAML format (via HTTP and console command)
• Import OpenAPI spec in JSON or YAML format (via config file)
• Define Symfony routes and OpenAPI Paths using the same attributes:
  • #[Post], #[Get], #[Put], #[Patch], #[Delete]
• Conditional OpenAPI Path/Route definition:
  • Example: #[Get('/me', when: 'service("toggle_me").isEnabled()')]
• Symfony attributes abbreviations:
  • #[Payload] instead of #[MapRequestPayload]
  • #[Query] instead of #[MapQueryString]
• OpenAPI attributes abbreviations:
  • #[Path] instead of #[PathParameter]
  • #[Param] instead of #[QueryParameter]
• Symfony's validation constraints definition using OpenAPI attributes:
  • Example: #[Property(minLength: 3, maxLength: 255)]
• Automatic controller response serialization (JSON format by default)
• Generate new endpoints from API spec (WIP) (based on open-solid/open-api-assistant-bundle)

License

This software is published under the MIT License