Extend OpenAPI Documentation

openapi expert

Extend OpenAPI Documentation

// src/App/ApiResource.php
namespace App\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\RequestBody;
use ApiPlatform\OpenApi\Model\Response;
#[Post(

To extend the OpenAPI documentation we use an OpenApi Operation model. When a field is not specified API Platform will add the missing informations.

    openapi: new Operation(
        responses: [
            '200' => new Response(description: 'Ok'),
        ],
        summary: 'Add a book to the library.',
        description: 'My awesome operation',

Each of the Operation field that you want to customize has a model in our OpenApi reference.

        requestBody: new RequestBody(
            content: new \ArrayObject(
                [
                    'application/ld+json' => [
                        'schema' => [
                            'properties' => [
                                'id' => ['type' => 'integer', 'required' => true, 'description' => 'id'],
                            ],
                        ],
                        'example' => [
                            'id' => 12345,
                        ],
                    ],
                ]
            )
        )
    )
)]
class Book
{
}

// src/App/Tests.php
namespace App\Tests;
use ApiPlatform\Playground\Test\TestGuideTrait;
use ApiPlatform\Symfony\Bundle\Test\ApiTestCase;
final class BookTest extends ApiTestCase
{
    use TestGuideTrait;
    public function testBookDoesNotExists(): void
    {
        $response = static::createClient()->request('GET', '/docs', options: ['headers' => ['accept' => 'application/vnd.openapi+json']]);
        $this->assertResponseStatusCodeSame(200);
        $this->assertJsonContains([
            'paths' => ['/books' => ['post' => ['summary' => 'Add a book to the library.', 'description' => 'My awesome operation']]],
        ]);
    }
}

You can also help us improve this guide.