mirrors/wallabag
1
0
Fork 0
mirror of https://github.com/wallabag/wallabag.git synced 2024-11-26 19:11:07 +00:00
Code Issues Projects Releases Wiki Activity

ApiDoc: Add response description to UserRestController

Browse source
This commit is contained in:
Casper Meijn 2023-07-02 08:27:07 +02:00
parent 0a6826cb4c
commit 4c797162bf
3 changed files with 86 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
src/Wallabag/ApiBundle/Controller/UserRestController.php
View file

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

20
src/Wallabag/ApiBundle/Entity/Client.php
View file

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

43
src/Wallabag/UserBundle/Entity/User.php
View file

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