Guides Extend OpenAPI Documentation

Extend OpenAPI Documentation

openapi expert
// 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;
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']]);
            'paths' => ['/books' => ['post' => ['summary' => 'Add a book to the library.', 'description' => 'My awesome operation']]],

You can also help us improve this guide.

Made with love by can help you design and develop your APIs and web projects, and train your teams in API Platform, Symfony, Next.js, Kubernetes and a wide range of other technologies.

Learn more

Copyright © 2023 Kévin Dunglas

Sponsored by