OpenAPITools / OpenAPITools/openapi-generator

[BUG] [JAXRS-JERSEY] Wrong mapping of the path "/:" (yaml-file) to '@Path("/default")' and not to '@Path("/")' (java-file)

Open
#10,622 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
26.8k
Forks
7.7k
PR metrics pending

Description

Description

This provides a test environment for the undesirable behaviour(s) (one to four) of the generated Java classes for:

...
paths:
  /:
...
  /foo:
...

We noticed this with the generator backend jaxrs-jersey in version 4.0.0. However, the problem still existed after an upgrade to 5.2.1..

But this could be unimportant if it is maybe a structural(?) problem that possibly affects all (code-) generators.

Reproducing

To be able to reproduce this, you need (at least) a Java (>= 1.8.0_301) and a maven (>= 3.6.1) installation. Then put the two files from this issue into a folder of your choice and start the generation; mvn alone is sufficient for this.

After the generation was successful (hopefully ;-)), change to the subfolder cd target/generated-sources/openapi and start the example application through mvn jetty:run .

Now you can successfully test the functioning of the endpoint /foo .

curl -X GET   'http://localhost:6666/issue/foo'

You will see something like:

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    41  100    41    0     0   8200      0 --:--:-- --:--:-- --:--:--  8200{"code":4,"type":"ok","message":"magic!"}

So far so goot.

But access to one level higher (/) fails!

$ curl -X GET  'http://localhost:6666/issue'
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   289  100   289    0     0  32111      0 --:--:-- --:--:-- --:--:-- 32111<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<title>Error 404 Not Found</title>
...

The assumption why this happens is an error in the generation of the corresponding Java class src/main/java/org/example/issue/generated/api/DefaultApi.java .

In line 28 stand the following annotation: @Path("/default") .

After stopping the jetty (mvn jetty:stop), do a bugfixing through change to @Path("/") and a restart of the jetty, access works as expected.

$ curl -X GET  'http://localhost:6666/issue'

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    41  100    41    0     0    301      0 --:--:-- --:--:-- --:--:--   301{"code":4,"type":"ok","message":"magic!"}

Workaround

This minimal API is just one part of a larger one we are working on. Our workaround is exactly the above change, but automated by

<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-patch-plugin</artifactId>
<version>1.2</version>

But it would be nice if this hack were no longer necessary in the foreseeable future!

Other stuff

Besides, three other generation problems can also be generated with this minimal application.

Double usage vs. Merging vs. Name generation

Since the root path / (yaml-file) is mapped to /default (java-file), the question arises, what actually happens when this endpoint is modeled? This is already prepared in the comment block.

...
# /default:
...

I would have expected at least a warning to appear during generation. A cancellation would be better.

But anyway, at the moment the results to be generated are simply merged.

And in the end, is the whole thing perhaps only of an academic nature?!?

As long as the operationId is unique and the above problem is fixed, everything is fine. Really? Unfortunately, the operationId is not a mandatory value. At least here, when specified, it is checked for duplicate values. But even that is unfortunately not consistent. Therefore, please comment out the specified operationId value at the top endpoint (/), uncomment the /default endpoint and specify its operationId with rootGet (instead of doDefaultGet). After a new mvn (without error) you can now see (.../DefaultApi.java) that the method name rootGet was chosen for the (still incorrectly routed) root endpoint (/) and the name, given by the specification, was changed. In my eyes, this is not an expected result.

Due to the lack of a possibility to choose a name for the default path (/) that cannot also be chosen via the specification (to my knowledge), the only remaining option for a final solution (fixing) is to generate/move the treatment class in another location (aka package). Either implicitly (e.g. ${apiPackage}.root/RootApi.java) or explicitly via a new configuration option (e.g. <rootPackage>...</rootPackage> with the default value from the apiPackage option (so that this change does not create any major upheavals for existing projects when they are upgraded)).

And an error message should always appear for duplicate operationId names, even if this only happens at the end of the tool chain when compiling. Of course, it would be better if an error message already appeared during API analysis if and which operationId names overlap, e.g. in the Swagger editor.

No models vs. Compilation errors

This minimal example is not as small as originally thought, because I had to insert something so that at least one model class is created. If no model is needed sematically, import statements are nevertheless created, which then produce compilation errors.

It would be better that the generation of such references is omitted, if the API does not include model generations (however useful or not that may always be).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Use the supplied minimal YAML and Maven setup with the jaxrs-jersey generator, run mvn, and inspect target/generated-sources/openapi/src/main/java/org/example/issue/generated/api/DefaultApi.java. Run the generated example with mvn jetty:run and compare the /foo and root endpoint requests. Done means the YAML root path is represented as @Path("/") and the root request succeeds without the workaround.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.