[PHP] Add support for server variables in operations (#12982)

* [FEATURE] Support for server variables in operations * [AUTOGENERATED] update samples * [PHP] Added tests for server variables in operations
OpenAPITools · Aug 3, 2022 · 1e3a39b · 1e3a39b
1 parent c9c0b62
commit 1e3a39b
Show file tree

Hide file tree

Showing 100 changed files with 1,733 additions and 2,937 deletions.
diff --git a/modules/openapi-generator/src/main/resources/php/Configuration.mustache b/modules/openapi-generator/src/main/resources/php/Configuration.mustache
@@ -496,32 +496,31 @@ class Configuration
     }
 
     /**
-     * Returns URL based on the index and variables
-     *
-     * @param int        $index     index of the host settings
-     * @param array|null $variables hash of variable and the corresponding value (optional)
-     * @return string URL based on host settings
-     */
-    public function getHostFromSettings($index, $variables = null)
+    * Returns URL based on host settings, index and variables
+    *
+    * @param array      $hostSettings array of host settings, generated from getHostSettings() or equivalent from the API clients
+    * @param int        $hostIndex    index of the host settings
+    * @param array|null $variables    hash of variable and the corresponding value (optional)
+    * @return string URL based on host settings
+    */
+    public static function getHostString(array $hostsSettings, $hostIndex, array $variables = null)
     {
         if (null === $variables) {
             $variables = [];
         }
 
-        $hosts = $this->getHostSettings();
-
         // check array index out of bound
-        if ($index < 0 || $index >= sizeof($hosts)) {
-            throw new \InvalidArgumentException("Invalid index $index when selecting the host. Must be less than ".sizeof($hosts));
+        if ($hostIndex < 0 || $hostIndex >= count($hostsSettings)) {
+            throw new \InvalidArgumentException("Invalid index $hostIndex when selecting the host. Must be less than ".count($hostsSettings));
         }
 
-        $host = $hosts[$index];
+        $host = $hostsSettings[$hostIndex];
         $url = $host["url"];
 
         // go through variable and assign a value
         foreach ($host["variables"] ?? [] as $name => $variable) {
             if (array_key_exists($name, $variables)) { // check to see if it's in the variables provided by the user
-                if (in_array($variables[$name], $variable["enum_values"], true)) { // check to see if the value is in the enum
+                if (!isset($variable['enum_values']) || in_array($variables[$name], $variable["enum_values"], true)) { // check to see if the value is in the enum
                     $url = str_replace("{".$name."}", $variables[$name], $url);
                 } else {
                     throw new \InvalidArgumentException("The variable `$name` in the host URL has invalid value ".$variables[$name].". Must be ".join(',', $variable["enum_values"]).".");
@@ -534,4 +533,16 @@ class Configuration
 
         return $url;
     }
+
+    /**
+     * Returns URL based on the index and variables
+     *
+     * @param int        $index     index of the host settings
+     * @param array|null $variables hash of variable and the corresponding value (optional)
+     * @return string URL based on host settings
+     */
+    public function getHostFromSettings($index, $variables = null)
+    {
+        return self::getHostString($this->getHostSettings(), $index, $variables);
+    }
 }
diff --git a/modules/openapi-generator/src/main/resources/php/api.mustache b/modules/openapi-generator/src/main/resources/php/api.mustache
diff --git a/modules/openapi-generator/src/main/resources/php/api_doc.mustache b/modules/openapi-generator/src/main/resources/php/api_doc.mustache
@@ -2,19 +2,33 @@
 
 {{.}}{{/description}}
 
-All URIs are relative to {{basePath}}.
+All URIs are relative to {{basePath}}, except if the operation defines another base path.
 
-Method | HTTP request | Description
-------------- | ------------- | -------------
-{{#operations}}{{#operation}}[**{{operationId}}()**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{summary}}
+| Method | HTTP request | Description |
+| ------------- | ------------- | ------------- |
+{{#operations}}{{#operation}}| [**{{operationId}}()**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{summary}} |
 {{/operation}}{{/operations}}{{#operations}}{{#operation}}
 
 ## `{{{operationId}}}()`
 
 ```php
 {{{operationId}}}({{#allParams}}${{paramName}}{{^-last}}, {{/-last}}{{/allParams}}){{#returnType}}: {{{.}}}{{/returnType}}
 ```
-
+{{#servers}}
+{{#-first}}
+### URI(s):
+{{/-first}}
+- {{{url}}} {{#description}}{{.}}{{/description}}{{#variables}}
+{{#-first}}
+    - Variables:
+{{/-first}}
+      - {{{name}}}: {{{description}}}{{^description}} No description provided{{/description}}{{#enumValues}}
+{{#-first}}
+        - Allowed values:
+{{/-first}}
+          - {{{.}}}{{/enumValues}}{{#defaultValue}}
+        - Default value: {{{.}}}
+{{/defaultValue}}{{/variables}}{{/servers}}
 {{{summary}}}{{#notes}}
 
 {{{.}}}{{/notes}}
@@ -34,15 +48,25 @@ $apiInstance = new {{invokerPackage}}\Api\{{classname}}(
 );
 {{^vendorExtensions.x-group-parameters}}
 {{#allParams}}${{paramName}} = {{{example}}}; // {{{dataType}}}{{#description}} | {{{.}}}{{/description}}
+{{/allParams}}{{#servers}}{{#-first}}
+$hostIndex = 0;
+$variables = [{{#variables}}
+    '{{{name}}}' => '{{{default}}}{{^default}}YOUR_VALUE{{/default}}',{{/variables}}
+];
+{{/-first}}{{/servers}}{{/vendorExtensions.x-group-parameters}}{{#vendorExtensions.x-group-parameters}}
+$associative_array = [
+{{#allParams}}    '{{paramName}}' => {{{example}}}, // {{{dataType}}}{{#description}} | {{{.}}}{{/description}}
 {{/allParams}}
-{{/vendorExtensions.x-group-parameters}}
-{{#vendorExtensions.x-group-parameters}}
-{{#allParams}}$associate_array['{{paramName}}'] = {{{example}}}; // {{{dataType}}}{{#description}} | {{{.}}}{{/description}}
-{{/allParams}}
+{{#servers}}{{#-first}}
+    'hostIndex' => 0,
+    $variables = [{{#variables}}
+        '{{{name}}}' => '{{{default}}}{{^default}}YOUR_VALUE{{/default}}',{{/variables}}
+    ],
+{{/-first}}{{/servers}}];
 {{/vendorExtensions.x-group-parameters}}
 
 try {
-    {{#returnType}}$result = {{/returnType}}$apiInstance->{{{operationId}}}({{^vendorExtensions.x-group-parameters}}{{#allParams}}${{paramName}}{{^-last}}, {{/-last}}{{/allParams}}{{/vendorExtensions.x-group-parameters}}{{#vendorExtensions.x-group-parameters}}$associate_array{{/vendorExtensions.x-group-parameters}});{{#returnType}}
+    {{#returnType}}$result = {{/returnType}}$apiInstance->{{{operationId}}}({{^vendorExtensions.x-group-parameters}}{{#allParams}}${{paramName}}{{^-last}}, {{/-last}}{{/allParams}}{{#servers}}{{#-first}}{{#allParams}}{{#-first}}, {{/-first}}{{/allParams}}$hostIndex, $variables{{/-first}}{{/servers}}{{/vendorExtensions.x-group-parameters}}{{#vendorExtensions.x-group-parameters}}$associate_array{{/vendorExtensions.x-group-parameters}});{{#returnType}}
     print_r($result);{{/returnType}}
 } catch (Exception $e) {
     echo 'Exception when calling {{classname}}->{{operationId}}: ', $e->getMessage(), PHP_EOL;
@@ -52,13 +76,15 @@ try {
 ### Parameters
 
 {{#vendorExtensions.x-group-parameters}}
-Note: the input parameter is an associative array with the keys listed as the parameter name below.
+Note: the input parameter is an associative array with the keys listed as the parameter names below.
 
 {{/vendorExtensions.x-group-parameters}}
-{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}Name | Type | Description  | Notes
-------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
-{{#allParams}} **{{paramName}}** | {{#isFile}}**{{{dataType}}}**{{/isFile}}{{#isPrimitiveType}}**{{{dataType}}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{^isFile}}[**{{{dataType}}}**](../Model/{{baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{description}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{.}}]{{/defaultValue}}
-{{/allParams}}
+{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}| Name | Type | Description  | Notes |
+| ------------- | ------------- | ------------- | ------------- |{{/-last}}{{/allParams}}
+{{#allParams}}| **{{paramName}}** | {{#isFile}}**{{{dataType}}}**{{/isFile}}{{#isPrimitiveType}}**{{{dataType}}}**{{/isPrimitiveType}}{{^isPrimitiveType}}{{^isFile}}[**{{{dataType}}}**](../Model/{{baseType}}.md){{/isFile}}{{/isPrimitiveType}}| {{description}} |{{^required}} [optional]{{/required}}{{#defaultValue}} [default to {{.}}]{{/defaultValue}} |
+{{/allParams}}{{#servers}}{{#-first}}| hostIndex | null|int | Host index. Defaults to null. If null, then the library will use $this->hostIndex instead | [optional] |
+| variables | array | Associative array of variables to pass to the host. Defaults to empty array. | [optional] |{{/-first}}
+{{/servers}}
 
 ### Return type
 

diff --git a/...api-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml b/...api-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml
@@ -33,6 +33,21 @@ paths:
     servers:
     - url: 'http://petstore.swagger.io/v2'
     - url: 'http://path-server-test.petstore.local/v2'
+    - url: 'http://{server}.swagger.io:{port}/v2'
+      description: test server with variables
+      variables:
+        server:
+          description: target server
+          enum:
+            - 'petstore'
+            - 'qa-petstore'
+            - 'dev-petstore'
+          default: 'petstore'
+        port:
+          enum:
+            - 80
+            - 8080
+          default: 80
     post:
       tags:
         - pet

diff --git a/samples/client/petstore/java/feign/api/openapi.yaml b/samples/client/petstore/java/feign/api/openapi.yaml
@@ -98,6 +98,21 @@ paths:
     servers:
     - url: http://petstore.swagger.io/v2
     - url: http://path-server-test.petstore.local/v2
+    - description: test server with variables
+      url: "http://{server}.swagger.io:{port}/v2"
+      variables:
+        server:
+          default: petstore
+          description: target server
+          enum:
+          - petstore
+          - qa-petstore
+          - dev-petstore
+        port:
+          default: "80"
+          enum:
+          - "80"
+          - "8080"
   /pet/findByStatus:
     get:
       description: Multiple status values can be provided with comma separated strings

diff --git a/samples/client/petstore/java/webclient/api/openapi.yaml b/samples/client/petstore/java/webclient/api/openapi.yaml
@@ -98,6 +98,21 @@ paths:
     servers:
     - url: http://petstore.swagger.io/v2
     - url: http://path-server-test.petstore.local/v2
+    - description: test server with variables
+      url: "http://{server}.swagger.io:{port}/v2"
+      variables:
+        server:
+          default: petstore
+          description: target server
+          enum:
+          - petstore
+          - qa-petstore
+          - dev-petstore
+        port:
+          default: "80"
+          enum:
+          - "80"
+          - "8080"
   /pet/findByStatus:
     get:
       description: Multiple status values can be provided with comma separated strings

diff --git a/samples/client/petstore/php/OpenAPIClient-php/docs/Api/AnotherFakeApi.md b/samples/client/petstore/php/OpenAPIClient-php/docs/Api/AnotherFakeApi.md
@@ -1,10 +1,10 @@
 # OpenAPI\Client\AnotherFakeApi
 
-All URIs are relative to http://petstore.swagger.io:80/v2.
+All URIs are relative to http://petstore.swagger.io:80/v2, except if the operation defines another base path.
 
-Method | HTTP request | Description
-------------- | ------------- | -------------
-[**call123TestSpecialTags()**](AnotherFakeApi.md#call123TestSpecialTags) | **PATCH** /another-fake/dummy | To test special tags
+| Method | HTTP request | Description |
+| ------------- | ------------- | ------------- |
+| [**call123TestSpecialTags()**](AnotherFakeApi.md#call123TestSpecialTags) | **PATCH** /another-fake/dummy | To test special tags |
 
 
 ## `call123TestSpecialTags()`
@@ -42,9 +42,9 @@ try {
 
 ### Parameters
 
-Name | Type | Description  | Notes
-------------- | ------------- | ------------- | -------------
- **client** | [**\OpenAPI\Client\Model\Client**](../Model/Client.md)| client model |
+| Name | Type | Description  | Notes |
+| ------------- | ------------- | ------------- | ------------- |
+| **client** | [**\OpenAPI\Client\Model\Client**](../Model/Client.md)| client model | |
 
 ### Return type
 

diff --git a/samples/client/petstore/php/OpenAPIClient-php/docs/Api/DefaultApi.md b/samples/client/petstore/php/OpenAPIClient-php/docs/Api/DefaultApi.md
@@ -1,10 +1,10 @@
 # OpenAPI\Client\DefaultApi
 
-All URIs are relative to http://petstore.swagger.io:80/v2.
+All URIs are relative to http://petstore.swagger.io:80/v2, except if the operation defines another base path.
 
-Method | HTTP request | Description
-------------- | ------------- | -------------
-[**fooGet()**](DefaultApi.md#fooGet) | **GET** /foo | 
+| Method | HTTP request | Description |
+| ------------- | ------------- | ------------- |
+| [**fooGet()**](DefaultApi.md#fooGet) | **GET** /foo |  |
 
 
 ## `fooGet()`