Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DbModel with openapiSchema #28

Merged
merged 13 commits into from
Sep 13, 2024
Merged

DbModel with openapiSchema #28

merged 13 commits into from
Sep 13, 2024

Conversation

siggi-k
Copy link

@siggi-k siggi-k commented Aug 21, 2024

  1. Added a new attribute openapiSchema to the DbModel. This allows passing arbitrary x-* metadata to the DbModel.
  2. The x-scenarios attribute includes name and description. It generates constants for scenarios. The advantage is that when using this schema.yaml for the frontend with a ClientGenerator, the scenarios will be identical in both models, frontend and backend.

The DbModel has received a new attribute called scenarioDefaultDescription.

Example:

project.yaml

x-scenarios:
  - name: create
    description: Scenario create this project
  - name: update

project.php

 /**
  * Scenario create this project
  */
 public const SCENARIO_CREATE = 'create';

 /**
  * Scenario update
  */
 public const SCENARIO_UPDATE = 'update';

...

 /**
  * Automatically generated scenarios from the model 'x-scenarios'.
  * @return array a list of scenarios and the corresponding active attributes.
  */
 public function scenarios()
 {
     /**
      * Each scenario is assigned attributes as in the 'default' scenario.
      * The advantage is that the scenario can be used immediately.
      * This can be overridden in the child model if needed.
      */
     $default = parent::scenarios()[self::SCENARIO_DEFAULT];

     return [
         self::SCENARIO_CREATE => $default,
         self::SCENARIO_UPDATE => $default,
         /**
          * The 'default' scenario and all scenarios mentioned in the rules() using 'on' and 'except'
          * are automatically included in the scenarios() function for the model.
          */
         ...parent::scenarios(),
     ];
 }

  1. For the x-scenarios, you can use your own scenarioDefaultDescription
    AcceptedInputs: {scenarioName}, {scenarioConst}, {modelName}

config.php

 [
     'class' => \cebe\yii2openapi\generator\ApiGenerator::class,
     'dbModel' => [
         /** AcceptedInputs: {scenarioName}, {scenarioConst}, {modelName}. @see DbModel::$scenarioDefaultDescription */
         'scenarioDefaultDescription' => implode("\n", [
             "This scenario name: \"{scenarioName}\"",
             "This scenario const: \"{scenarioConst}\"",
             "This model name: \"{modelName}\"",
         ]),
     ],

project.php

 /**
  * Scenario create this project
  */
 public const SCENARIO_CREATE = 'create';

 /**
  * This scenario name: "update"
  * This scenario const: "SCENARIO_UPDATE"
  * This model name: "Project"
  */
 public const SCENARIO_UPDATE = 'update';
  1. A warning is now displayed at the top of the Model class: This file is generated by Gii, do not change manually!

  2. The Model class description now has a fallback if no description is provided. Fallback: This is the model class for table <tableName>.

  3. The "bug with spaces" in the Model class description has been fixed, so that code style no longer complains. The description is now formatted using cebe\yii2openapi\lib\helpers\FormatHelper::getFormattedDescription.

  4. cebe\yii2openapi\lib\items\Attribute::getFormattedDescription has been renamed to cebe\yii2openapi\lib\items\Attribute::getPropertyAnnotation.
    There are two reasons for this:

    • The property annotation consists of: phpType + columnName + description (from the description field in model.yaml). It is not ideal to label this as "description" since it can cause confusion.
    • In a PHPDoc comment, the description usually explains what a class, method, or property does. However, these lines are annotations within the PHPDoc comment, using the @property tag to indicate that the model class has properties like id, name, etc. Such annotations are meant to inform tools like IDEs (e.g., PhpStorm) or documentation generators about the properties of the class, especially when these properties are not directly visible in the code (e.g., through magic methods like __get() and __set()).
  5. The "bug with spaces" in the property annotation has also been fixed, so that code style no longer complains. The description is formatted using cebe\yii2openapi\lib\helpers\FormatHelper::getFormattedDescription.

@siggi-k siggi-k force-pushed the openapiSchema branch 5 times, most recently from 5169b8e to f546b4c Compare August 22, 2024 12:02
@siggi-k siggi-k force-pushed the openapiSchema branch 2 times, most recently from b5ddc82 to 36d3a0e Compare August 22, 2024 14:58
src/lib/items/DbModel.php Outdated Show resolved Hide resolved
src/lib/items/DbModel.php Show resolved Hide resolved
src/lib/items/DbModel.php Show resolved Hide resolved
src/lib/Config.php Outdated Show resolved Hide resolved
@siggi-k siggi-k force-pushed the openapiSchema branch 2 times, most recently from 32acea6 to fd024be Compare September 13, 2024 10:10
@siggi-k siggi-k force-pushed the openapiSchema branch 5 times, most recently from d96095b to 36c4107 Compare September 13, 2024 11:16
@cebe cebe merged commit 2db7968 into php-openapi:master Sep 13, 2024
5 checks passed
@cebe
Copy link
Member

cebe commented Sep 13, 2024

Thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants