Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow Custom OpenAPI Override via YAML File #427

Open
aynaitlamine opened this issue Jul 11, 2024 · 1 comment · May be fixed by #430
Open

Allow Custom OpenAPI Override via YAML File #427

aynaitlamine opened this issue Jul 11, 2024 · 1 comment · May be fixed by #430

Comments

@aynaitlamine
Copy link

Description

I would like to request the addition of a feature that allows developers to override the OpenAPI documentation via a YAML file instead of using the OpenApiFactory class. This would make the process easier and more readable. Currently, overriding the OpenAPI documentation requires the use of the OpenApiFactory class, which can be less intuitive and harder to manage for complex configurations. By enabling YAML-based overrides, developers can leverage the simplicity and readability of YAML to define their custom OpenAPI documentation.

Example

Here is a simple example of how this feature could be implemented.

Current Method (Using OpenApiFactory Class):

<?php
namespace App\OpenApi;

use ApiPlatform\OpenApi\Factory\OpenApiFactoryInterface;
use ApiPlatform\OpenApi\OpenApi;
use ApiPlatform\OpenApi\Model;

class OpenApiFactory implements OpenApiFactoryInterface
{

    public function __construct(private OpenApiFactoryInterface $decorated)
    {
    }

    public function __invoke(array $context = []): OpenApi
    {
        $openApi = $this->decorated->__invoke($context);
        $pathItem = $openApi->getPaths()->getPath('/api/grumpy_pizzas/{id}');
        $operation = $pathItem->getGet();

        $openApi->getPaths()->addPath('/api/grumpy_pizzas/{id}', $pathItem->withGet(
            $operation->withParameters(array_merge(
                $operation->getParameters(),
                [new Model\Parameter('fields', 'query', 'Fields to remove of the output')]
            ))
        ));

        $openApi = $openApi->withInfo((new Model\Info('New Title', 'v2', 'Description of my custom API'))->withExtensionProperty('info-key', 'Info value'));
        $openApi = $openApi->withExtensionProperty('key', 'Custom x-key value');
        $openApi = $openApi->withExtensionProperty('x-value', 'Custom x-value value');

        // to define base path URL
        $openApi = $openApi->withServers([new Model\Server('https://foo.bar')]);

        return $openApi;
    }
}

Proposed Method (Using YAML File):

# config/openapi/custom_openapi.yaml

openapi:
  paths:
    /custom/path:
      get:
        summary: "Custom Path Summary"
        responses:
          '200':
            description: "Successful response"

Example Configuration in services.yaml:

services:
  App\OpenApi\CustomOpenApiFactory:
    decorates: 'api_platform.openapi.factory'
    arguments: ['@App\OpenApi\CustomOpenApiFactory.inner', '%kernel.project_dir%/config/openapi/custom_openapi.yaml']
    

In this example, the custom OpenAPI modifications are specified in a YAML file, which is then injected into the OpenApiFactory class. This approach enhances readability and maintainability, especially for large-scale projects with complex OpenAPI customizations.

@PawelSuwinski
Copy link
Contributor

It still works with Api Platform Core 3.x as openapiContext attribute. I am using it extensively however as deprecated it will be removed in AP Core 4.x so one would have to face it in the future.

It seems that here is no elegant way to implement openapi support in the shema-generator, ex. ApiPlatform\OpenApi\Model classes implements fluent and immutable interface that is not too friendly for denormalizers so it needs manual explicit initialization.

Currently, overriding the OpenAPI documentation requires the use of the OpenApiFactory class, which can be less intuitive and harder to manage for complex configurations.

Maybe more clearly would be with some configurator pattern for ApiResource by decorating ResourceMetadataCollectionFactoryInterface.

@PawelSuwinski PawelSuwinski linked a pull request Sep 20, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants