RetailCRM-Mirror/NelmioApiDocBundle
1
0
Fork 0
mirror of https://github.com/retailcrm/NelmioApiDocBundle.git synced 2025-02-02 23:59:26 +03:00
Code Issues Projects Releases Wiki Activity

[Docs] Add PHP Attributes examples (#1985)

Browse Source 
* [Docs] Add PHP Attributes examples

* Fix namespaces
This commit is contained in:
Krystian Marcisz 2022-04-30 20:25:41 +02:00 committed by GitHub
parent 05d16e6814
commit 6ac4f07872
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 203 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

274
Resources/doc/index.rst
View File

@ -17,6 +17,8 @@ This bundle supports *Symfony* route requirements, PHP annotations, `Swagger-Php
For models, it supports the `Symfony serializer`_ , the `JMS serializer`_ and the `willdurand/Hateoas`_ library. For models, it supports the `Symfony serializer`_ , the `JMS serializer`_ and the `willdurand/Hateoas`_ library.
It does also support `Symfony form`_ types. It does also support `Symfony form`_ types.
Attributes are supported from version 4.7 and PHP 8.1.
Migrate from 3.x to 4.0 Migrate from 3.x to 4.0
----------------------- -----------------------
@ -137,45 +139,91 @@ You can configure global information in the bundle configuration ``documentation
To document your routes, you can use the SwaggerPHP annotations and the To document your routes, you can use the SwaggerPHP annotations and the
``Nelmio\ApiDocBundle\Annotation\Model`` annotation in your controllers:: ``Nelmio\ApiDocBundle\Annotation\Model`` annotation in your controllers::
namespace AppBundle\Controller; .. configuration-block::
use AppBundle\Entity\User; .. code-block:: php-annotations
use AppBundle\Entity\Reward;
use Nelmio\ApiDocBundle\Annotation\Model; namespace AppBundle\Controller;
use Nelmio\ApiDocBundle\Annotation\Security;
use OpenApi\Annotations as OA;
use Symfony\Component\Routing\Annotation\Route;
class UserController use AppBundle\Entity\User;
{ use AppBundle\Entity\Reward;
/** use Nelmio\ApiDocBundle\Annotation\Model;
* List the rewards of the specified user. use Nelmio\ApiDocBundle\Annotation\Security;
* use OpenApi\Annotations as OA;
* This call takes into account all confirmed awards, but not pending or refused awards. use Symfony\Component\Routing\Annotation\Route;
*
* @Route("/api/{user}/rewards", methods={"GET"}) class UserController
* @OA\Response(
* response=200,
* description="Returns the rewards of an user",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref=@Model(type=Reward::class, groups={"full"}))
* )
* )
* @OA\Parameter(
* name="order",
* in="query",
* description="The field used to order rewards",
* @OA\Schema(type="string")
* )
* @OA\Tag(name="rewards")
* @Security(name="Bearer")
*/
public function fetchUserRewardsAction(User $user)
{ {
// ... /**
* List the rewards of the specified user.
*
* This call takes into account all confirmed awards, but not pending or refused awards.
*
* @Route("/api/{user}/rewards", methods={"GET"})
* @OA\Response(
* response=200,
* description="Returns the rewards of an user",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref=@Model(type=Reward::class, groups={"full"}))
* )
* )
* @OA\Parameter(
* name="order",
* in="query",
* description="The field used to order rewards",
* @OA\Schema(type="string")
* )
* @OA\Tag(name="rewards")
* @Security(name="Bearer")
*/
public function fetchUserRewardsAction(User $user)
{
// ...
}
} }
}
.. code-block:: php-attributes
namespace AppBundle\Controller;
use AppBundle\Entity\User;
use AppBundle\Entity\Reward;
use Nelmio\ApiDocBundle\Annotation\Model;
use Nelmio\ApiDocBundle\Annotation\Security;
use OpenApi\Attributes as OA;
use Symfony\Component\Routing\Annotation\Route;
class UserController
{
/**
* List the rewards of the specified user.
*
* This call takes into account all confirmed awards, but not pending or refused awards.
*/
#[Route('/api/{user}/rewards', methods=['GET'])]
#[OA\Response(
response: 200,
description: 'Returns the rewards of an user',
content: new OA\JsonContent(
type: 'array',
items: new OA\Items(ref: new Model(type: AlbumDto::class, groups: ['full']))
)
)]
#[OA\Parameter(
name: 'order',
in: 'query',
description: 'The field used to order rewards',
schema: new OA\Schema(type: 'string')
)]
#[OA\Tag(name: 'rewards')]
#[Security(name: 'Bearer')]
public function fetchUserRewardsAction(User $user)
{
// ...
}
}
The normal PHPdoc block on the controller method is used for the summary and description. The normal PHPdoc block on the controller method is used for the summary and description.
@ -199,21 +247,46 @@ This annotation has two options:
* ``type`` to specify your model's type:: * ``type`` to specify your model's type::
/** .. configuration-block::
* @OA\Response(
* response=200, .. code-block:: php-annotations
*     @Model(type=User::class)
* ) /**
*/ * @OA\Response(
* response=200,
*     @Model(type=User::class)
* )
*/
.. code-block:: php-attributes
#[OA\Response(
response: 200,
description: 'Successful response',
content: new Model(type: User::class)
)]
* ``groups`` to specify the serialization groups used to (de)serialize your model:: * ``groups`` to specify the serialization groups used to (de)serialize your model::
/**
* @OA\Response( .. configuration-block::
* response=200,
*     @Model(type=User::class, groups={"non_sensitive_data"}) .. code-block:: php-annotations
* )
*/ /**
* @OA\Response(
* response=200,
*     @Model(type=User::class, groups={"non_sensitive_data"})
* )
*/
.. code-block:: php-attributes
#[OA\Response(
response: 200,
description: 'Successful response',
content: new Model(type: User::class, groups: ['non_sensitive_data'])
)]
.. tip:: .. tip::
@ -224,6 +297,10 @@ This annotation has two options:
To use ``@Model`` directly within a ``@OA\Schema``, ``@OA\Items`` or ``@OA\Property``, you have to use the ``$ref`` field:: To use ``@Model`` directly within a ``@OA\Schema``, ``@OA\Items`` or ``@OA\Property``, you have to use the ``$ref`` field::
.. configuration-block::
.. code-block:: php-annotations
/** /**
* @OA\Response( * @OA\Response(
* @OA\JsonContent(ref=@Model(type=User::class)) * @OA\JsonContent(ref=@Model(type=User::class))
@ -238,6 +315,23 @@ This annotation has two options:
* )) * ))
*/ */
.. code-block:: php-attributes
#[OA\Response(
content: new OA\JsonContent(ref: new Model(type: User::class))
)]
/**
* or
*/
#[OA\Response(
content: new OA\XmlContent(example: new OA\Schema(
type: 'object',
properties: [
new OA\Property(property: 'foo', ref: new Model(type: FooClass::class))
]
))
)]
Symfony Form types Symfony Form types
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
@ -288,7 +382,15 @@ General PHP objects
.. code-block:: php .. code-block:: php
@OA\Schema(ref=@Model(type="App\Response\ItemResponse", groups=["Default"])), .. configuration-block::
.. code-block:: php-annotations
@OA\Schema(ref=@Model(type="App\Response\ItemResponse", groups=["Default"])),
.. code-block:: php-attributes
#[OA\Schema(ref: new Model(type: App\Response\ItemResponse::class, groups: ['Default']))]
It will generate two different component schemas (ItemResponse, ItemResponse2), even though Default and blank are the same. This is by design. It will generate two different component schemas (ItemResponse, ItemResponse2), even though Default and blank are the same. This is by design.
@ -306,34 +408,64 @@ General PHP objects
If you want to customize the documentation of an object's property, you can use ``@OA\Property``:: If you want to customize the documentation of an object's property, you can use ``@OA\Property``::
use Nelmio\ApiDocBundle\Annotation\Model;
use OpenApi\Annotations as OA;
class User .. configuration-block::
{
/**
* @var int
* @OA\Property(description="The unique identifier of the user.")
*/
public $id;
/** .. code-block:: php-annotations
* @OA\Property(type="string", maxLength=255)
*/ use Nelmio\ApiDocBundle\Annotation\Model;
public $username; use OpenApi\Annotations as OA;
/** class User
* @OA\Property(ref=@Model(type=User::class)) {
*/ /**
public $friend; * @var int
* @OA\Property(description="The unique identifier of the user.")
*/
public $id;
/** /**
* @OA\Property(description="This is my coworker!") * @OA\Property(type="string", maxLength=255)
*/ */
public setCoworker(User $coworker) { public $username;
// ...
/**
* @OA\Property(ref=@Model(type=User::class))
*/
public $friend;
/**
* @OA\Property(description="This is my coworker!")
*/
public setCoworker(User $coworker) {
// ...
}
}
.. code-block:: php-attributes
use Nelmio\ApiDocBundle\Annotation\Model;
use OpenApi\Attributes as OA;
class User
{
/**
* @var int
*/
#[OA\Property(description: 'The unique identifier of the user.')]
public $id;
#[OA\Property(type: 'string', maxLength: 255)]
public $username;
#[OA\Property(ref: new Model(type: User::class))]
public $friend;
#[OA\Property(description: 'This is my coworker!')]
public setCoworker(User $coworker) {
// ...
}
} }
}
See the `OpenAPI 3.0 specification`__ to see all the available fields of ``@OA\Property``. See the `OpenAPI 3.0 specification`__ to see all the available fields of ``@OA\Property``.