Guides
Extend OpenAPI Documentation
September 19-20, 2024 | Lille & online
The international conference on the API Platform Framework
Get ready for game-changing announcements for the PHP community!
The API Platform Conference 2024 is happening soon, and it's close to selling out.
API Platform 4, Caddy web server, Xdebug, AI... Enjoy two days of inspiring talks with our friendly community and our amazing speakers.
Guide
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;
#[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']]],
]);
}
}
