Support changing default table schema property name

cnizzardini · Sep 7, 2024 · 095e4eb · 095e4eb
1 parent 491ffec
commit 095e4eb
Show file tree

Hide file tree

Showing 3 changed files with 17 additions and 11 deletions.
diff --git a/docs/attributes.md b/docs/attributes.md
@@ -539,6 +539,7 @@ Class level attribute for modifying OpenAPI Schema.
 | [visibility](#visibility) | int `1`        | No      | Determines the visibility of the schema, see OpenApiSchema class constants |
 | title                     | ?string `null` | Yes     | Overwrites the default title                                               |
 | description               | ?string `null` | Yes     | Overwrites the default description (if any)                                |
+| name                      | ?string `null` | Yes     | The name of the OpenAPI property [defaults to the CakePHP table alias].    |
 
 #### Visibility
 
@@ -554,7 +555,7 @@ You can use the constants below when defining `visibility`:
 Example:
 
 ```php
-#[OpenApiSchema(visbility: OpenApiSchema::VISIBLE_ALWAYS, title: 'Always visible schema')]
+#[OpenApiSchema(visbility: OpenApiSchema::VISIBLE_ALWAYS, title: 'Always visible schema', name: 'RenamedCakeTableAlias')]
 class Actor extends Entity{}
 ```
 

diff --git a/src/Lib/Attribute/OpenApiSchema.php b/src/Lib/Attribute/OpenApiSchema.php
@@ -32,14 +32,16 @@ class OpenApiSchema
     public const VISIBLE_NEVER = 4;
 
     /**
-     * @param int $visibility See class constants for options.
-     * @param string|null $title The title of the schema
-     * @param string|null $description The description of the schema
+     * @param int $visibility See class constants for options [default: VISIBLE_DEFAULT].
+     * @param string|null $title The title of the schema [default: null].
+     * @param string|null $description The description of the schema [default: null].
+     * @param string|null $name The name of the OpenAPI property [defaults to the CakePHP table alias].
      */
     public function __construct(
-        public readonly int $visibility = 1,
+        public readonly int $visibility = self::VISIBLE_DEFAULT,
         public readonly ?string $title = null,
-        public readonly ?string $description = null
+        public readonly ?string $description = null,
+        public readonly ?string $name = null
     ) {
         if ($this->visibility < 1 || $this->visibility > 4) {
             throw new InvalidArgumentException(
@@ -56,6 +58,7 @@ public function __construct(
     public function createSchema(): Schema
     {
         return (new Schema($this->title))
+            ->setName($this->name)
             ->setVisibility($this->visibility)
             ->setDescription($this->description);
     }

diff --git a/src/Lib/Schema/SchemaFactory.php b/src/Lib/Schema/SchemaFactory.php
@@ -61,8 +61,10 @@ public function create(ModelDecorator $modelDecorator, int $propertyType = 6): ?
             return null;
         }
 
+        $name = $openApiSchema instanceof OpenApiSchema ? $openApiSchema->name : null;
+
         $schema = $this
-            ->createSchema($modelDecorator->getModel(), $propertyType)
+            ->createSchema($modelDecorator->getModel(), $propertyType, $name)
             ->setVisibility($openApiSchema->visibility ?? OpenApiSchema::VISIBLE_DEFAULT)
             ->setDescription($openApiSchema->description ?? '');
 
@@ -84,17 +86,17 @@ public function create(ModelDecorator $modelDecorator, int $propertyType = 6): ?
      * @return \SwaggerBake\Lib\OpenApi\Schema
      * @throws \ReflectionException
      */
-    public function createAlways(ModelDecorator $modelDecorator, int $propertyType = 6): Schema
+    public function createAlways(ModelDecorator $modelDecorator, int $propertyType = 6, ?string $name = null): Schema
     {
-        return $this->createSchema($modelDecorator->getModel(), $propertyType);
+        return $this->createSchema($modelDecorator->getModel(), $propertyType, $name);
     }
 
     /**
      * @param \MixerApi\Core\Model\Model $model Model instance
      * @param int $propertyType see public constants for options
      * @return \SwaggerBake\Lib\OpenApi\Schema
      */
-    private function createSchema(Model $model, int $propertyType = 6): Schema
+    private function createSchema(Model $model, int $propertyType = 6, ?string $name = null): Schema
     {
         $this->validator = $this->getValidator($model);
 
@@ -103,7 +105,7 @@ private function createSchema(Model $model, int $propertyType = 6): Schema
         $properties = $this->getProperties($model, $propertyType, $docBlock);
 
         $schema = (new Schema())
-            ->setName((new ReflectionClass($model->getEntity()))->getShortName())
+            ->setName($name ?? (new ReflectionClass($model->getEntity()))->getShortName())
             ->setType('object')
             ->setProperties($properties);