OpenAPI generator not following the specification regarding to schemes - PHP

[thomasphansen]

Description

According to the OpenAPI-Specification v2.0, for the fixed field "schemes":

The transfer protocol of the API. Values MUST be from the list: "http", "https", "ws", "wss". If the schemes is not included, the default scheme to be used is the one used to access the Swagger definition itself.

The link below points to the swagger definition for the TripleTex API. Please, notice that the "schemes" field is NOT defined.

Swagger php generator works perfectly for this definition. This is a snippet from the lib/Configuration.php file:

class Configuration
{
    # (...)

    /**
     * The host
     *
     * @var string
     */
    protected $host = 'https://tripletex.no/v2';

   # (...)
}

However, when I use OpenAPI generator, the Configuration class lacks the "https" information:

class Configuration
{
    # (...)

    /**
     * The host
     *
     * @var string
     */
    protected $host = 'tripletex.no/v2';

   # (...)
}

Also, if I download the json file and run the swagger generator, it will by default add the https, while OpenAPI generator will continue to give the same output above. This is not a surprise, since there is nothing on the OpenAPI specification that would suggest this "default" behaviour - even if it is a breaking change. But the first situation (getting the scheme from the swagger definition URL) is clearly a bug...

openapi-generator version

v3.0.0

OpenAPI declaration file content or url

https://tripletex.no/v2/swagger.json

Command line used for generation

docker pull openapitools/openapi-generator-cli
docker run
--user $(id -u):$(id -g)
--rm -v ${PWD}:/local openapitools/openapi-generator-cli:v3.0.0 generate -i https://tripletex.no/v2/swagger.json
-l php
-o /local
-c /local/config.json

Steps to reproduce

1. create a local config.json file, with the following content:

{
	"invokerPackage": "Tripletex",
	"modelPackage": "Model",
	"apiPackage": "Api",
	"packagePath": "",
	"composerVendorName": "spysystem",
	"composerProjectName": "tripletex-integration"
}

2. check the generated file lib/Configuration.php for the protected $host parameter

Related issues/PRs

Suggest a fix/enhancement

[jmini]

Thank you a lot for this report. It seems that we need to add something. Is https:// always the default?

---

In the OpenAPI v3 specification, server url is defined by:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#serverObject

My understanding is that in OAS3 you must specify a scheme like "http", "https", "ws", "wss" when you have an absolute URL.

Maybe the swagger-parser should add the default scheme during v2 to v3 conversion... We will see.

[wing328]

@thomasphansen thanks for reporting the issue. I agree this issue should be addressed according to the v2 spec that you quoted above.

As a workaround, please set the schemes (an array) to https in the spec (saved locally to your local drive) for the time being.

[thomasphansen]

Hello William,
Thank you for the quick reply! :)
The swagger definition I presented is not maintained by me - it belongs to TripleTex, which I am just
integrating to. I could of course download their file and change the schemes field, but that would mean trouble whenever they add new functionalities to it (which actually happens every 2 weeks, according to their support). For now, my solution is to change the host variable after creating the Api Client, since it is pretty unlike that the host will change in a short future. But thank you anyway! :)

[jmini]

@thomasphansen: do you know if https:// is the default when nothing is specified? Is that specified somewhere?

[thomasphansen]

Hi Jérémie, as I said before: the only thing specified about this in OpenAPI 2.0 (here) is:

If the schemes is not included, the default scheme to be used is the one used to access the Swagger definition itself.

Which means, if you try to generate the code from https://tripletex.no/v2/swagger.json, it should use https, and if you try from http://tripletex.no/v2/swagger.json, then it should be http. This is the bug I am reporting.

For local files, it is (of course) impossible to choose, and in this case, Swagger and OpenAPI generators behavior could differ, since there is no specification for that on OpenAPI. But if you want to keep compatibility with existing Swagger files, I'd recommend to keep the current behavior and use https as default, if the schemes field is not present.

[jmini]

Which means, if you try to generate the code from https://tripletex.no/v2/swagger.json, it should use https, and if you try from http://tripletex.no/v2/swagger.json, then it should be http.

Now it makes sense to me. Sorry if I did not understood it from the beginning.

I still think that this is a Swagger-Parser issue. Lets do some investigations and maybe file an issue there.

[wing328]

I still think that this is a Swagger-Parser issue. Lets do some investigations and maybe file an issue there.

I also think it's a swagger parser issue. In OpenAPI Generator, we can default it to "https" if it's not defined.

[thomasphansen]

I have a question: My call to the generator is something like:

docker run --user $(id -u):$(id -g) --rm -v ${PWD}:/local openapitools/openapi-generator-cli:v3.0.0 generate -i https://tripletex.no/v2/swagger.json -l php -o /local 

, which means the source for the "swagger" definition is https://tripletex.no/v2/swagger.json. Is the swagger-parser receiving this link, or its contents?

Because if it gets the link, then it is able to follow the OpenAPI specs and find the correct scheme from the link itself. Otherwise, then I guess it is the generator that will need to do it, since the swagger-parser will have no way of knowing that the original link contains "https"...