Skip to content
GitLab
Closed
Issue created by Administrator@rootContributor

[PHP] [Improvement] Make Api return object instead of array

Created by: thomasphansen

Description

Today a given "myOperation" operation will have four methods declared on an API:

  • myOperation()
  • myOperationWithHttpInfo()
  • myOperationAsync()
  • myOperationAsyncWithHttpInfo()

The two last ones will return promisses, containing the same answer as the first two. The first one returns either {{returnType}} or void, depending on if there is a returnType. (This is actually wrong, but it is being targeted in PR128, linked to issue #125 (closed))

But my problem is with the myOperatorWithHttpInfo() method: it returns an array with three elements:

  • the message itself (response)
  • the status code
  • and an array with headers.

Considering the best practices for OOP, and comparing with other language generators that compound this project (for example, the C# generator), this method should rather return an Object that describes the API Response. Such an object should contain getters for each of the three elements (getMessage(), getStatus(), getHeaders() ).

My improvement suggestion (I'll push a PR as soon as I finish this description) is to add another class to the client, called ApiResponse (just like we already have in the C# client generator). This class will be the return for a class of methods ending with *WithApiResponse(), which will replace the existing *WithHttpInfo() ones and offer a more OOP-like interface for interacting with the API Response.

I can see two challenges with this approach:

  1. Typing the message (return). This is already a problem for the *WithHttpInfo() methods, and is being solved with the addition of the following phpDoc in moustache:
* @return array of {{#returnType}}{{{returnType}}}{{/returnType}}{{^returnType}}null{{/returnType}}, HTTP status code, HTTP response headers (array of strings)

, which results in something like:

 * @return array of MyResponseClass, HTTP status code, HTTP response headers (array of strings)

I suggest using the same approach:

* @return APIResponse with "message" property of type MyResponseClass

, which is not a perfect solution, but can be used until the Generics RFC gets an implementation and becomes approved.

  1. Backwards compatibility. I have no idea of what is your current approach to breaking changes, though my previous experience with swagger tells me that it is not a big concern. Just in case, my PR will keep the existing *WithHttpInfo() methods, but will change its implementation to use the *WithApiResponse() ones internally.
openapi-generator version

Prepare 3.0.3-SNAPSHOT

OpenAPI declaration file content or url

not applicable.

Command line used for generation

./bin/php-petstore.php, from the project root folder

Steps to reproduce

not applicable

Related issues/PRs

not applicable/not found

Suggest a fix/enhancement

will push a PR on this issue