From 4c797162bfd50c5ec74d31e796822758a9050e20 Mon Sep 17 00:00:00 2001 From: Casper Meijn Date: Sun, 2 Jul 2023 08:27:07 +0200 Subject: [PATCH] ApiDoc: Add response description to UserRestController --- .../Controller/UserRestController.php | 31 +++++++++---- src/Wallabag/ApiBundle/Entity/Client.php | 20 +++++++++ src/Wallabag/UserBundle/Entity/User.php | 43 +++++++++++++++++++ 3 files changed, 86 insertions(+), 8 deletions(-) diff --git a/src/Wallabag/ApiBundle/Controller/UserRestController.php b/src/Wallabag/ApiBundle/Controller/UserRestController.php index 64888b33d..fdba8422a 100644 --- a/src/Wallabag/ApiBundle/Controller/UserRestController.php +++ b/src/Wallabag/ApiBundle/Controller/UserRestController.php @@ -8,6 +8,7 @@ use FOS\UserBundle\Event\UserEvent; use FOS\UserBundle\FOSUserEvents; use FOS\UserBundle\Model\UserManagerInterface; use JMS\Serializer\SerializationContext; +use Nelmio\ApiDocBundle\Annotation\Model; use Nelmio\ApiDocBundle\Annotation\Operation; use OpenApi\Annotations as OA; use Symfony\Component\EventDispatcher\EventDispatcherInterface; @@ -28,7 +29,8 @@ class UserRestController extends WallabagRestController * summary="Retrieve current logged in user informations.", * @OA\Response( * response="200", - * description="Returned when successful" + * description="Returned when successful", + * @Model(type=User::class, groups={"user_api"})) * ) * ) * @@ -52,32 +54,45 @@ class UserRestController extends WallabagRestController * @OA\RequestBody( * @OA\JsonContent( * type="object", - * required={"username", "password", "email", "client_name"}, + * required={"username", "password", "email"}, * @OA\Property( * property="username", * description="The user's username", - * @OA\Schema(type="string") + * type="string", + * example="wallabag", * ), * @OA\Property( * property="password", * description="The user's password", - * @OA\Schema(type="string") + * type="string", + * example="hidden_value", * ), * @OA\Property( * property="email", * description="The user's email", - * @OA\Schema(type="string") + * type="string", + * example="wallabag@wallabag.io", * ), * @OA\Property( * property="client_name", * description="The client name (to be used by your app)", - * @OA\Schema(type="string") + * type="string", + * example="Fancy App", * ), * ) * ), * @OA\Response( - * response="200", - * description="Returned when successful" + * response="201", + * description="Returned when successful", + * @Model(type=User::class, groups={"user_api_with_client"})), + * ), + * @OA\Response( + * response="403", + * description="Server doesn't allow registrations" + * ), + * @OA\Response( + * response="400", + * description="Request is incorrectly formatted" * ) * ) * diff --git a/src/Wallabag/ApiBundle/Entity/Client.php b/src/Wallabag/ApiBundle/Entity/Client.php index 78349820a..6760864e8 100644 --- a/src/Wallabag/ApiBundle/Entity/Client.php +++ b/src/Wallabag/ApiBundle/Entity/Client.php @@ -7,6 +7,7 @@ use FOS\OAuthServerBundle\Entity\Client as BaseClient; use JMS\Serializer\Annotation\Groups; use JMS\Serializer\Annotation\SerializedName; use JMS\Serializer\Annotation\VirtualProperty; +use OpenApi\Annotations as OA; use Wallabag\UserBundle\Entity\User; /** @@ -27,6 +28,12 @@ class Client extends BaseClient * * @ORM\Column(name="name", type="text", nullable=false) * + * @OA\Property( + * description="Name of the API client", + * type="string", + * example="Default Client", + * ) + * * @Groups({"user_api_with_client"}) */ protected $name; @@ -44,6 +51,12 @@ class Client extends BaseClient /** * @var string * + * @OA\Property( + * description="Client secret used for authorization", + * type="string", + * example="2lmubx2m9vy80ss8c4wwcsg8ok44s88ocwcc8wo0w884oc8440", + * ) + * * @SerializedName("client_secret") * @Groups({"user_api_with_client"}) */ @@ -94,6 +107,13 @@ class Client extends BaseClient /** * @VirtualProperty + * + * @OA\Property( + * description="Client secret used for authorization", + * type="string", + * example="3_1lpybsn0od40css4w4ko8gsc8cwwskggs8kgg448ko0owo4c84", + * ) + * * @SerializedName("client_id") * @Groups({"user_api_with_client"}) */ diff --git a/src/Wallabag/UserBundle/Entity/User.php b/src/Wallabag/UserBundle/Entity/User.php index ab8115e73..9d05929e8 100644 --- a/src/Wallabag/UserBundle/Entity/User.php +++ b/src/Wallabag/UserBundle/Entity/User.php @@ -8,6 +8,8 @@ use FOS\UserBundle\Model\User as BaseUser; use JMS\Serializer\Annotation\Accessor; use JMS\Serializer\Annotation\Groups; use JMS\Serializer\Annotation\XmlRoot; +use Nelmio\ApiDocBundle\Annotation\Model; +use OpenApi\Annotations as OA; use Scheb\TwoFactorBundle\Model\BackupCodeInterface; use Scheb\TwoFactorBundle\Model\Email\TwoFactorInterface as EmailTwoFactorInterface; use Scheb\TwoFactorBundle\Model\Google\TwoFactorInterface as GoogleTwoFactorInterface; @@ -40,6 +42,12 @@ class User extends BaseUser implements EmailTwoFactorInterface, GoogleTwoFactorI * @ORM\Id * @ORM\GeneratedValue(strategy="AUTO") * + * @OA\Property( + * description="The unique numeric id of the user", + * type="int", + * example=12, + * ) + * * @Groups({"user_api", "user_api_with_client"}) */ protected $id; @@ -49,6 +57,12 @@ class User extends BaseUser implements EmailTwoFactorInterface, GoogleTwoFactorI * * @ORM\Column(name="name", type="text", nullable=true) * + * @OA\Property( + * description="The personal Name of the user", + * type="string", + * example="Walla Baggger", + * ) + * * @Groups({"user_api", "user_api_with_client"}) */ protected $name; @@ -56,6 +70,12 @@ class User extends BaseUser implements EmailTwoFactorInterface, GoogleTwoFactorI /** * @var string * + * @OA\Property( + * description="The unique username of the user", + * type="string", + * example="wallabag", + * ) + * * @Groups({"user_api", "user_api_with_client"}) */ protected $username; @@ -63,6 +83,12 @@ class User extends BaseUser implements EmailTwoFactorInterface, GoogleTwoFactorI /** * @var string * + * @OA\Property( + * description="E-mail address of the user", + * type="string", + * example="wallabag@wallabag.io", + * ) + * * @Groups({"user_api", "user_api_with_client"}) */ protected $email; @@ -72,6 +98,12 @@ class User extends BaseUser implements EmailTwoFactorInterface, GoogleTwoFactorI * * @ORM\Column(name="created_at", type="datetime") * + * @OA\Property( + * description="Creation date of the user account. (In ISO 8601 format)", + * type="string", + * example="2023-06-27T19:25:44+0000", + * ) + * * @Groups({"user_api", "user_api_with_client"}) */ protected $createdAt; @@ -81,6 +113,12 @@ class User extends BaseUser implements EmailTwoFactorInterface, GoogleTwoFactorI * * @ORM\Column(name="updated_at", type="datetime") * + * @OA\Property( + * description="Update date of the user account. (In ISO 8601 format)", + * type="string", + * example="2023-06-27T19:37:30+0000", + * ) + * * @Groups({"user_api", "user_api_with_client"}) */ protected $updatedAt; @@ -112,6 +150,11 @@ class User extends BaseUser implements EmailTwoFactorInterface, GoogleTwoFactorI /** * @see getFirstClient() below * + * @OA\Property( + * description="Default client created during user registration. Used for further authorization", + * ref=@Model(type=Client::class, groups={"user_api_with_client"}) + * ) + * * @Groups({"user_api_with_client"}) * @Accessor(getter="getFirstClient") */