Merge branches 'master' and '22-bug-rules-required-is-generated-before-_default' of github.com:php-openapi/yii2-openapi into 22-bug-rules-required-is-generated-before-_default

Author: SOHELAHMED7

.github/workflows/test.yml

@@ -22,7 +22,6 @@ jobs:
       matrix:
         php-versions: ['7.4', '8.0', '8.1', '8.2', '8.3']
 
-    # TODO use cache
     steps:
       - uses: actions/checkout@v3
 
@@ -42,6 +41,21 @@ jobs:
       - name: docker-compose up
         run: make up
 
+      # https://github.com/shivammathur/setup-php?tab=readme-ov-file#cache-composer-dependencies
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "dir=./tests/tmp/.composer/cache/files" >> $GITHUB_OUTPUT
+
+      - name: Make tests dir writable for restoring cache in next step
+        run: make tests_dir_write_permission
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('composer.json') }}
+          restore-keys: ${{ runner.os }}-composer-
+
       - name: Install Docker and composer dependencies
         run: docker-compose exec php php -v && make installdocker
 

CONTRIBUTING.md

@@ -10,7 +10,7 @@ cd yii2-openapi
 make clean_all
 make up
 make installdocker
-sudo chmod -R 777 tests/tmp/ # https://github.com/cebe/yii2-openapi/issues/156
+sudo chmod -R 777 tests/tmp/ # TODO avoid 777 https://github.com/cebe/yii2-openapi/issues/156
 make migrate
 
 # to check everything is setup up correctly ensure all tests passes
@@ -95,6 +95,14 @@ with Zend OPcache v7.4.27, Copyright (c), by Zend Technologies
 with Xdebug v2.9.6, Copyright (c) 2002-2020, by Derick Rethans
 ```
 
+If a PHP version is changed as mentioned above, then following operations must be performed:
+
+```
+rm -rf vendor
+rm -rf composer.lock
+composer install
+```
+
 Issues and solutions
 --------------------
 

Makefile

@@ -39,13 +39,15 @@ up:
 	echo "Waiting for mariadb to start up..."
 	docker-compose exec -T mysql timeout 60s sh -c "while ! (mysql -udbuser -pdbpass -h maria --execute 'SELECT 1;' > /dev/null 2>&1); do echo -n '.'; sleep 0.1 ; done; echo 'ok'" || (docker-compose ps; docker-compose logs; exit 1)
 
-	# Solution to problem https://stackoverflow.com/questions/50026939/php-mysqli-connect-authentication-method-unknown-to-the-client-caching-sha2-pa
-	# if updated to PHP 7.4 or more, this command is not needed (TODO)
-	docker-compose exec -T mysql timeout 60s sh -c "while ! (mysql --execute \"ALTER USER 'dbuser'@'%' IDENTIFIED WITH mysql_native_password BY 'dbpass';\" > /dev/null 2>&1); do echo -n '.'; sleep 0.1 ; done; echo 'ok'" || (docker-compose ps; docker-compose logs; exit 1)
+	echo "Waiting for Mysql to start up..."
+	docker-compose exec -T mysql timeout 60s sh -c "while ! (mysql -udbuser -pdbpass -h mysql --execute 'SELECT 1;' > /dev/null 2>&1); do echo -n '.'; sleep 0.1 ; done; echo 'ok'" || (docker-compose ps; docker-compose logs; exit 1)
 
 cli:
 	docker-compose exec --user=$(UID) php bash
 
+cli_root:
+	docker-compose exec --user="root" php bash
+
 cli_mysql:
 	docker-compose exec --user=$(UID) mysql bash
 
@@ -57,6 +59,9 @@ migrate:
 installdocker:
 	docker-compose run --user=$(UID) --rm php composer install && chmod +x tests/yii
 
+tests_dir_write_permission:
+	docker-compose run --user="root" --rm php chmod -R 777 tests/tmp/ # TODO avoid 777 https://github.com/cebe/yii2-openapi/issues/156
+
 testdocker:
 	docker-compose run --user=$(UID) --rm php sh -c 'vendor/bin/phpunit --repeat 3'
 

README.md

@@ -76,7 +76,9 @@ return $config;
 
 To use the web generator, open `index.php?r=gii` and select the `REST API Generator`.
 
-On console you can run the generator with `./yii gii/api --openApiPath=@app/openapi.yaml`. Where `@app/openapi.yaml` should be the absolute path to your OpenAPI spec file. This can be JSON as well as YAML (see also [php-openapi/php-openapi](https://github.com/php-openapi/php-openapi/) for supported formats).
+On console, you can run the generator with `./yii gii/api --openApiPath=@app/openapi.yaml`. Where `@app/openapi.yaml`
+should be the absolute path to your OpenAPI spec file. This can be JSON as well as YAML (see
+also [php-openapi/php-openapi](https://github.com/php-openapi/php-openapi/) for supported formats).
 
 Run `./yii gii/api --help` for all options. Example: Disable generation of migrations files `./yii gii/api --generateMigrations=0`
 
@@ -212,6 +214,14 @@ Specify table indexes
            default: '{}' 
 ```
 
+If raw DB expression is needed in index, then it must be for only one column. Example:
+
+```yaml
+    x-indexes:
+       - "gin(to_tsvector('english', search::text)):search" # valid
+       - "gin(to_tsvector('english', search::text)):search,column2" # invalid
+```
+
 ### `x-db-default-expression`
 
 Ability to provide default value by database expression
@@ -309,15 +319,215 @@ Provide custom database table column name in case of relationship column. This w
               - x-fk-column-name: redelivery_of # this will create `redelivery_of` column instead of `redelivery_of_id`
 ```
 
+
+### `x-deleted-schemas`
+
+This is root level key used to generate "drop table" migration for the deleted component schema. If a component schema (DB model) is removed from OpenAPI spec then its following entities should be also deleted from the code:
+
+ - DB table (migrations)
+ - model
+ - faker
+
+So to generate appropriate migration for the removed schema, explicitly setting schema name or schema name + custom table name is required in this key. Only then the migrations will be generated. It should be set as:
+
+```yaml
+x-deleted-schemas:
+  - Fruit # Example: table name is evaluated to `itt_fruits`, if `itt_` is prefix set in DB config
+  - Mango: the_mango_table_name # custom table name; see `x-table` in README.md
+```
+
+### `x-no-relation`
+
+To differentiate a component schema property from one-to-many or many-to-many relation in favour of array(json) of
+related objects, `x-no-relation` (type: boolean, default: false) is used.
+
+```yaml
+        comments:
+          type: array
+          items:
+            $ref: "#/components/schemas/Comment"
+```
+
+This will not generate 'comments' column in database migrations. But it will generate `getComments()` relation in Yii model file.
+
+In order to make it real database column, extension `x-no-relation` can be used.
+
+```yaml
+        comments:
+          type: array
+          x-no-relation: true
+          items:
+            $ref: "#/components/schemas/Comment"
+```
+
+Database column type can be `array`, `json` etc. to store such data.
+
+Now if the Comment schema from the above example is
+
+```yaml
+    Comment:
+      properties:
+        id:
+          type: integer
+        content:
+          type: string
+```
+
+then the value for `comments` can be
+
+```json
+[
+  {
+    "id": 1,
+    "content": "Hi there"
+  },
+  {
+    "id": 2,
+    "content": "Hi there 2"
+  }
+]
+```
+
+`x-no-relation` can be only used with OpenAPI schema data type `array`.
+
+### `x-route`
+
+To customize route (controller ID/action ID) for a path, use custom key `x-route` with value `<controller ID>/<action ID>`. It can be used for non-crud paths. It must be used under HTTP method key but not
+directly under the `paths` key of OpenAPI spec. Example:
+
+```yaml
+paths:
+  /payments/invoice/{invoice}:
+    parameters:
+      - name: invoice
+        in: path
+        description: lorem ipsum
+        required: true
+        schema:
+          type: integer
+    post:
+      x-route: 'payments/invoice'
+      summary: Pay Invoice
+      description: Pay for Invoice with given invoice number
+      requestBody:
+        description: Record new payment for an invoice
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Payments'
+        required: true
+      responses:
+        '200':
+          description: Successfully paid the invoice
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Success'
+```
+
+It won't generate `actionCreateInvoice` in `PaymentsController.php` file, but will generate `actionInvoice` instead in
+same file.
+
+Generated URL rules config for above is (in `urls.rest.php` or pertinent file):
+```php
+    'POST payments/invoice/<invoice:\d+>' => 'payments/invoice',
+    'payments/invoice/<invoice:\d+>' => 'payments/options',
+```
+
+Also, if same action is needed for HTTP GET and POST then use same value for `x-route`. Example:
+
+```yaml
+paths:
+  /a1/b1:
+    get:
+      x-route: 'abc/xyz'
+      operationId: opnid1
+      summary: List
+      description: Lists
+      responses:
+        '200':
+          description: The Response
+    post:
+      x-route: 'abc/xyz'
+      operationId: opnid2
+      summary: create
+      description: create
+      responses:
+        '200':
+          description: The Response
+```
+
+Generated URL rules config for above is (in `urls.rest.php` or pertinent file):
+```php
+    'GET a1/b1' => 'abc/xyz',
+    'POST a1/b1' => 'abc/xyz',
+    'a1/b1' => 'abc/options',
+```
+`x-route` does not support [Yii Modules](https://www.yiiframework.com/doc/guide/2.0/en/structure-modules).
+
+### `x-description-is-comment`
+
+    boolean; default: false
+
+When a new database table is created from new OpenAPI component schema, description of a property will be used as
+comment of column (of database table).
+
+This extension is used when a description is edited for existing property, and you want to generate migration for its
+corresponding column comment changes.
+
+This extension can be used at 3 place:
+
+**1. root level (highest priority)**
+
+```yaml
+openapi: 3.0.3
+x-description-is-comment: true
+info:
+  title: Description
+```
+
+This will create migration of any changed description of component schema property present throughout the spec.
+
+**2. component schema level**
+
+```yaml
+components:
+  schemas:
+    Fruit:
+      type: object
+      x-description-is-comment: true
+```
+
+This will create migration of changed description of only properties of component schema which have this extension.
+
+**3. property level (lowest priority)**
+
+```yaml
+components:
+  schemas:
+    Fruit:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+          nullable: false
+          x-description-is-comment: true
+          description: Hi there
+```
+
+Migrations will be only generated for changed description of properties having this extension.
+
 ## Many-to-Many relation definition
 
 There are two ways for define many-to-many relations:
 
 ### Simple many-to-many without junction model
 
    - property name for many-to-many relation should be equal lower-cased, pluralized related schema name
-     
-   - referenced schema should contains mirrored reference to current schema
+
+- referenced schema should contain mirrored reference to current schema
 
    - migration for junction table can be generated automatically - table name should be [pluralized, lower-cased
  schema_name1]2[pluralized, lower-cased schema name2], in alphabetical order;
@@ -390,7 +600,7 @@ User:
 `NOT NULL` in DB migrations is determined by `nullable` and `required` properties of the OpenAPI schema.
 e.g. attribute = 'my_property'.
 
-- If you define attribute neither "required" nor via "nullable", then it is by default `NULL`:
+- If you define attribute neither "required" nor via "nullable", then it is by default `NULL` ([opposite of OpenAPI spec](https://swagger.io/specification/v3/?sbsearch=nullable)):
 
 ```yaml
   ExampleSchema:
@@ -508,12 +718,13 @@ created_at:
 ## Assumptions
 
 When generating code from an OpenAPI description there are many possible ways to achive a fitting result.
-Thus there are some assumptions and limitations that are currently applied to make this work.
+Thus, there are some assumptions and limitations that are currently applied to make this work.
 Here is a (possibly incomplete) list:
 
 - The current implementation works best with OpenAPI description that follows the [JSON:API](https://jsonapi.org/) guidelines.
   - The request and response format/schema is currently not extracted from OpenAPI schema and may need to be adjusted manually if it does not follow JSON:API
-- column/field/property with name `id` is considered as Primary Key by this library and it is automatically handled by DB/Yii; so remove it from validation `rules()`
+- column/field/property with name `id` is considered as Primary Key by this library, and it is automatically handled by
+  DB/Yii; so remove it from validation `rules()`
   - other fields can currently be used as primary keys using the `x-pk` OpenAPI extension (see below) but it may not be work correctly in all cases, please report bugs if you find them.
 
 Other things to keep in mind:

composer.json

@@ -19,19 +19,20 @@
 	},
 	"require": {
 		"php": "^7.4 || ^8.0",
-		"cebe/php-openapi": "^1.5.0",
+		"cebe/php-openapi": "^1.7.0",
 		"yiisoft/yii2": "~2.0.48",
 		"yiisoft/yii2-gii": "~2.0.0 | ~2.1.0 | ~2.2.0| ~2.3.0",
 		"laminas/laminas-code": ">=3.4 <=4.13",
-		"php-openapi/yii2-fractal": "^1.0.0",
+		"php-openapi/yii2-fractal": "^1.4",
 		"fakerphp/faker": "^1.9",
-		"sam-it/yii2-mariadb": "^2.0"
+		"sam-it/yii2-mariadb": "^2.0",
+		"symfony/var-exporter": "^5.4",
+		"symfony/polyfill-php80": "^1.31"
 	},
 	"require-dev": {
 		"cebe/indent": "*",
 		"friendsofphp/php-cs-fixer": "~2.16",
 		"phpunit/phpunit": "^8.0",
-		"symfony/polyfill-php80": "^1.16",
 		"yiisoft/yii2-gii": ">=2.1.0"
 	},
 	"autoload": {

docker-compose.yml

@@ -41,11 +41,11 @@ services:
             MYSQL_DATABASE: testdb
 
     maria:
-        image: mariadb:10.8
+        image: mariadb:10.8.2
         ports:
             - '23306:3306'
         volumes:
-            - ./tests/tmp/maria:/var/lib/mysql:rw
+            - ./tests/tmp/mariadb:/var/lib/mariadb:rw
         environment:
             # TZ: UTC
             # MARIADB_ALLOW_EMPTY_PASSWORD: 1