feat(EntityGenerator): Added ApiProperty documentation for generated …

…entities non-virtual fields
roadiz · Jan 18, 2024 · 61ca78e · 61ca78e
1 parent c7e3825
commit 61ca78e
Show file tree

Hide file tree

Showing 6 changed files with 189 additions and 15 deletions.
diff --git a/src/Entity/Document.php b/src/Entity/Document.php
@@ -6,6 +6,7 @@
 
 use ApiPlatform\Doctrine\Orm\Filter as BaseFilter;
 use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Metadata\ApiProperty;
 use ApiPlatform\Serializer\Filter\PropertyFilter;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
@@ -79,6 +80,9 @@ class Document extends AbstractDateTimed implements AdvancedDocumentInterface, H
     #[ORM\Column(name: 'copyright_valid_since', type: 'datetime', nullable: true)]
     #[SymfonySerializer\Groups(['document_copyright'])]
     #[Serializer\Groups(['document_copyright'])]
+    #[ApiProperty(
+        description: 'Document copyright starting date',
+    )]
     protected ?\DateTime $copyrightValidSince = null;
 
     /**
@@ -87,6 +91,9 @@ class Document extends AbstractDateTimed implements AdvancedDocumentInterface, H
     #[ORM\Column(name: 'copyright_valid_until', type: 'datetime', nullable: true)]
     #[SymfonySerializer\Groups(['document_copyright'])]
     #[Serializer\Groups(['document_copyright'])]
+    #[ApiProperty(
+        description: 'Document copyright expiry date',
+    )]
     protected ?\DateTime $copyrightValidUntil = null;
 
     /**
@@ -143,6 +150,10 @@ class Document extends AbstractDateTimed implements AdvancedDocumentInterface, H
     #[SymfonySerializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Type("string")]
+    #[ApiProperty(
+        description: 'Embed ID on external platforms',
+        example: 'FORSwsjtQSE',
+    )]
     #[Assert\Length(max: 250)]
     protected ?string $embedId = null;
 
@@ -167,6 +178,10 @@ class Document extends AbstractDateTimed implements AdvancedDocumentInterface, H
     #[Serializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Type('string')]
     #[Assert\Length(max: 100)]
+    #[ApiProperty(
+        description: 'Embed platform name',
+        example: 'youtube',
+    )]
     protected ?string $embedPlatform = null;
     /**
      * @var Collection<int, NodesSourcesDocuments>
@@ -235,6 +250,10 @@ class Document extends AbstractDateTimed implements AdvancedDocumentInterface, H
     #[Serializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Type('string')]
     #[Assert\Length(max: 255)]
+    #[ApiProperty(
+        description: 'Document file mime type',
+        example: 'image/jpeg',
+    )]
     private ?string $mimeType = null;
     /**
      * @var Collection<int, DocumentInterface>
@@ -267,6 +286,10 @@ class Document extends AbstractDateTimed implements AdvancedDocumentInterface, H
     #[SymfonySerializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Type('int')]
+    #[ApiProperty(
+        description: 'When document has visual size: width in pixels',
+        example: '1280',
+    )]
     private int $imageWidth = 0;
     /**
      * @var integer
@@ -275,6 +298,10 @@ class Document extends AbstractDateTimed implements AdvancedDocumentInterface, H
     #[SymfonySerializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Type('int')]
+    #[ApiProperty(
+        description: 'When document has visual size: height in pixels',
+        example: '800',
+    )]
     private int $imageHeight = 0;
     /**
      * @var integer
@@ -283,6 +310,10 @@ class Document extends AbstractDateTimed implements AdvancedDocumentInterface, H
     #[SymfonySerializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Type('int')]
+    #[ApiProperty(
+        description: 'When document is audio or video: duration in seconds',
+        example: '300',
+    )]
     private int $mediaDuration = 0;
     /**
      * @var string|null
@@ -292,6 +323,10 @@ class Document extends AbstractDateTimed implements AdvancedDocumentInterface, H
     #[Serializer\Groups(['document', 'document_display', 'nodes_sources', 'tag', 'attribute'])]
     #[Serializer\Type('string')]
     #[Assert\Length(max: 7)]
+    #[ApiProperty(
+        description: 'When document is image: average color in hexadecimal format',
+        example: '#ffffff'
+    )]
     private ?string $imageAverageColor = null;
     /**
      * @var int|null The filesize in bytes.
@@ -619,6 +654,10 @@ public function setFilesize(?int $filesize): static
         Serializer\SerializedName("alt"),
         SymfonySerializer\Groups(["document", "document_display", "nodes_sources", "tag", "attribute"]),
         SymfonySerializer\SerializedName("alt"),
+        ApiProperty(
+            description: 'Document alternative text, for img HTML tag.',
+            writable: false,
+        )
     ]
     public function getAlternativeText(): string
     {

diff --git a/src/Entity/Node.php b/src/Entity/Node.php
@@ -5,6 +5,7 @@
 namespace RZ\Roadiz\CoreBundle\Entity;
 
 use ApiPlatform\Doctrine\Orm\Filter as BaseFilter;
+use ApiPlatform\Metadata\ApiProperty;
 use ApiPlatform\Serializer\Filter\PropertyFilter;
 use ApiPlatform\Metadata\ApiFilter;
 use Doctrine\Common\Collections\ArrayCollection;
@@ -92,6 +93,10 @@ class Node extends AbstractDateTimedPositioned implements LeafInterface, Attribu
     #[Assert\NotNull]
     #[Assert\NotBlank]
     #[Assert\Length(max: 255)]
+    #[ApiProperty(
+        description: 'Unique node name (slug) used to build content URL',
+        example: 'this-is-a-node-name',
+    )]
     private string $nodeName = '';
 
     #[ORM\Column(name: 'dynamic_node_name', type: 'boolean', nullable: false, options: ['default' => true])]
@@ -107,6 +112,10 @@ class Node extends AbstractDateTimedPositioned implements LeafInterface, Attribu
     #[SymfonySerializer\Groups(['nodes_sources_base', 'nodes_sources', 'node'])]
     #[Serializer\Groups(['nodes_sources_base', 'nodes_sources', 'node'])]
     #[Gedmo\Versioned]
+    #[ApiProperty(
+        description: 'Is this node visible in website navigation?',
+        example: 'true',
+    )]
     private bool $visible = true;
 
     /**
@@ -128,6 +137,10 @@ class Node extends AbstractDateTimedPositioned implements LeafInterface, Attribu
     #[SymfonySerializer\Groups(['node'])]
     #[Serializer\Groups(['node'])]
     #[Gedmo\Versioned]
+    #[ApiProperty(
+        description: 'Is this node locked to prevent deletion and renaming?',
+        example: 'false',
+    )]
     private bool $locked = false;
 
     /**
@@ -143,26 +156,53 @@ class Node extends AbstractDateTimedPositioned implements LeafInterface, Attribu
     #[SymfonySerializer\Groups(['node'])]
     #[Serializer\Groups(['node'])]
     #[Gedmo\Versioned]
+    #[ApiProperty(
+        description: 'Does this node act as a container for other nodes?',
+        example: 'false',
+    )]
     private bool $hideChildren = false;
 
     #[ORM\Column(type: 'boolean', nullable: false, options: ['default' => false])]
     #[SymfonySerializer\Groups(['node'])]
     #[Serializer\Groups(['node'])]
     #[Gedmo\Versioned]
+    #[ApiProperty(
+        description: 'Can this node hold other nodes inside?',
+        example: 'false',
+    )]
     private bool $sterile = false;
 
     #[ORM\Column(name: 'children_order', type: 'string', length: 50)]
     #[SymfonySerializer\Groups(['node', 'node_listing'])]
     #[Serializer\Groups(['node', 'node_listing'])]
     #[Assert\Length(max: 50)]
     #[Gedmo\Versioned]
+    #[ApiProperty(
+        description: 'This node children will be sorted by a given field',
+        example: 'position',
+        schema: [
+            'type' => 'string',
+            'enum' => ['position', 'nodeName', 'createdAt', 'updatedAt', 'publishedAt'],
+            'example' => 'position'
+        ],
+    )]
     private string $childrenOrder = 'position';
 
     #[ORM\Column(name: 'children_order_direction', type: 'string', length: 4)]
     #[SymfonySerializer\Groups(['node', 'node_listing'])]
     #[Serializer\Groups(['node', 'node_listing'])]
     #[Assert\Length(max: 4)]
+    #[Assert\Choice(choices: ['ASC', 'DESC'])]
     #[Gedmo\Versioned]
+    #[ApiProperty(
+        description: 'This node children will be sorted ascendant or descendant',
+        example: 'ASC',
+        schema: [
+            'type' => 'string',
+            'enum' => ['ASC', 'DESC'],
+            'example' => 'ASC'
+        ],
+    )]
     private string $childrenOrderDirection = 'ASC';
 
     /**

diff --git a/src/Entity/NodesSources.php b/src/Entity/NodesSources.php
@@ -5,6 +5,7 @@
 namespace RZ\Roadiz\CoreBundle\Entity;
 
 use ApiPlatform\Doctrine\Orm\Filter as BaseFilter;
+use ApiPlatform\Metadata\ApiProperty;
 use ApiPlatform\Serializer\Filter\PropertyFilter;
 use ApiPlatform\Metadata\ApiFilter;
 use Doctrine\Common\Collections\ArrayCollection;
@@ -73,6 +74,10 @@ class NodesSources extends AbstractEntity implements Loggable
     #[Serializer\Groups(['nodes_sources', 'nodes_sources_base', 'log_sources'])]
     #[Gedmo\Versioned]
     #[Assert\Length(max: 250)]
+    #[ApiProperty(
+        description: 'Content title',
+        example: 'This is a title',
+    )]
     protected ?string $title = null;
 
     #[ApiFilter(BaseFilter\DateFilter::class)]
@@ -82,6 +87,9 @@ class NodesSources extends AbstractEntity implements Loggable
     #[SymfonySerializer\Groups(['nodes_sources', 'nodes_sources_base'])]
     #[Serializer\Groups(['nodes_sources', 'nodes_sources_base'])]
     #[Gedmo\Versioned]
+    #[ApiProperty(
+        description: 'Content publication date and time',
+    )]
     protected ?\DateTime $publishedAt = null;
 
     #[ApiFilter(BaseFilter\SearchFilter::class, strategy: "partial")]
@@ -90,6 +98,10 @@ class NodesSources extends AbstractEntity implements Loggable
     #[Serializer\Groups(['nodes_sources'])]
     #[Gedmo\Versioned]
     #[Assert\Length(max: 150)]
+    #[ApiProperty(
+        description: 'Title for search engine optimization, used in HTML title tag',
+        example: 'This is a title',
+    )]
     protected string $metaTitle = '';
 
     #[ORM\Column(name: 'meta_keywords', type: 'text')]
@@ -103,13 +115,21 @@ class NodesSources extends AbstractEntity implements Loggable
     #[SymfonySerializer\Groups(['nodes_sources'])]
     #[Serializer\Groups(['nodes_sources'])]
     #[Gedmo\Versioned]
+    #[ApiProperty(
+        description: 'Description for search engine optimization, used in HTML meta description tag',
+        example: 'This is a description',
+    )]
     protected string $metaDescription = '';
 
     #[ApiFilter(BaseFilter\BooleanFilter::class)]
     #[ORM\Column(name: 'no_index', type: 'boolean', options: ['default' => false])]
     #[SymfonySerializer\Groups(['nodes_sources'])]
     #[Serializer\Groups(['nodes_sources'])]
     #[Gedmo\Versioned]
+    #[ApiProperty(
+        description: 'Do not allow robots to index this content, used in HTML meta robots tag',
+        example: 'false',
+    )]
     protected bool $noIndex = false;
 
     #[ApiFilter(BaseFilter\SearchFilter::class, properties: [

diff --git a/src/Entity/Tag.php b/src/Entity/Tag.php
@@ -5,6 +5,7 @@
 namespace RZ\Roadiz\CoreBundle\Entity;
 
 use ApiPlatform\Doctrine\Orm\Filter as BaseFilter;
+use ApiPlatform\Metadata\ApiProperty;
 use ApiPlatform\Serializer\Filter\PropertyFilter;
 use ApiPlatform\Metadata\ApiFilter;
 use Doctrine\Common\Collections\ArrayCollection;
@@ -61,6 +62,10 @@ class Tag extends AbstractDateTimedPositioned implements LeafInterface
     #[SymfonySerializer\Groups(['tag', 'tag_base', 'color'])]
     #[Serializer\Groups(['tag', 'tag_base', 'color'])]
     #[Assert\Length(max: 7)]
+    #[ApiProperty(
+        description: 'Tag color in hexadecimal format.',
+        example: '#ff0000',
+    )]
     protected string $color = '#000000';
 
     /**
@@ -117,6 +122,10 @@ class Tag extends AbstractDateTimedPositioned implements LeafInterface
     #[Assert\NotNull]
     #[Assert\NotBlank]
     #[Assert\Length(max: 250)]
+    #[ApiProperty(
+        description: 'Unique tag name (slug) used to build content URL or filter queries.',
+        example: 'this-is-a-tag-name',
+    )]
     private string $tagName = '';
 
     #[SymfonySerializer\Ignore]
@@ -127,24 +136,50 @@ class Tag extends AbstractDateTimedPositioned implements LeafInterface
     #[ORM\Column(type: 'boolean', nullable: false, options: ['default' => true])]
     #[SymfonySerializer\Groups(['tag', 'tag_base', 'node', 'nodes_sources'])]
     #[Serializer\Groups(['tag', 'tag_base', 'node', 'nodes_sources'])]
+    #[ApiProperty(
+        description: 'Is this tag visible in website?',
+        example: 'true',
+    )]
     private bool $visible = true;
 
     #[ORM\Column(name: 'children_order', type: 'string', length: 60, options: ['default' => 'position'])]
     #[SymfonySerializer\Ignore]
     #[Serializer\Groups(["tag"])]
     #[Assert\Length(max: 60)]
+    #[ApiProperty(
+        description: 'This tag children will be sorted by a given field',
+        example: 'position',
+        schema: [
+            'type' => 'string',
+            'enum' => ['position', 'tagName', 'createdAt', 'updatedAt', 'publishedAt'],
+            'example' => 'position'
+        ],
+    )]
     private string $childrenOrder = 'position';
 
     #[ORM\Column(name: 'children_order_direction', type: 'string', length: 4, options: ['default' => 'ASC'])]
     #[SymfonySerializer\Ignore]
     #[Serializer\Groups(["tag"])]
     #[Assert\Length(max: 4)]
+    #[ApiProperty(
+        description: 'This tag children will be sorted ascendant or descendant',
+        example: 'ASC',
+        schema: [
+            'type' => 'string',
+            'enum' => ['ASC', 'DESC'],
+            'example' => 'ASC'
+        ],
+    )]
     private string $childrenOrderDirection = 'ASC';
 
     #[ApiFilter(BaseFilter\BooleanFilter::class)]
     #[ORM\Column(type: 'boolean', nullable: false, options: ['default' => false])]
     #[SymfonySerializer\Ignore]
     #[Serializer\Groups(["tag"])]
+    #[ApiProperty(
+        description: 'Is this tag locked to prevent deletion and renaming?',
+        example: 'false',
+    )]
     private bool $locked = false;
 
     /**
@@ -468,4 +503,17 @@ public function setParent(?LeafInterface $parent = null): static
 
         return $this;
     }
+
+
+    #[ApiProperty(
+        description: 'Unique tag name (slug) used to build content URL or filter queries.',
+        example: 'this-is-a-tag-name',
+    )]
+    #[SymfonySerializer\SerializedName('slug')]
+    #[SymfonySerializer\Groups(['tag', 'tag_base', 'node', 'nodes_sources'])]
+    #[Serializer\Groups(['tag', 'tag_base', 'node', 'nodes_sources'])]
+    public function getSlug(): string
+    {
+        return $this->getTagName();
+    }
 }