ApiDoc: Add response description to UserRestController

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",
+     *         response="201",
-     *         description="Returned when successful"
+     *         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"
      *     )
      * )
      *

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"})
      */

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")
      */