Add externalDocs to @Operation to the JavaSpring generator #14177

arey · 2022-12-05T09:36:13Z

This Pull Request implements the feature describe in #14141 with a TDD approach.
It adds an externalDocs attribute to the @Operation annotation regarding the operation yaml specification.

PR checklist

[ X] Read the contribution guidelines.
[ X] Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
[ X] Run the following to build the project and update samples
[X ] File the PR against the correct branch: master (6.3.0) (minor release - breaking changes with fallbacks), 7.0.x (breaking changes without fallbacks)
[ X] If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.
For JavaSpring comitttee
@cachescrubber (2022/02) @welshm (2022/02) @MelleD (2022/02) @atextor (2022/02) @manedev79 (2022/02) @javisst (2022/02) @borsch (2022/02) @banlevente (2022/02) @Zomzog (2022/09)
Core Team : @wing328 @jimschubert @cbornet @jmini @etherealjoy @spacether

…enerator

arey · 2022-12-05T10:18:08Z

The ci/circle1:node1 test has crashed with this error:

Caused by: java.lang.UnsupportedClassVersionError: org/springframework/boot/maven/RepackageMojo has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 52.0
    at java.lang.ClassLoader.defineClass1 (Native Method)

welshm

Can you also regenerate the samples? Or do none of the samples have exeternal docs? If not, perhaps we should add one?

welshm · 2022-12-05T15:11:29Z

modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultCodegen.java

@@ -4478,6 +4478,7 @@ else if (one.required)
        op.requiredParams = requiredParams;
        op.optionalParams = optionalParams;
        op.externalDocs = operation.getExternalDocs();
+        op.hasExternalDocs = op.externalDocs != null;


You're making changes to DefaultCodegen and CodegenOperation so you'll also likely need a review from the core team as well (even though this is minor)

We could maybe initiate the hasExternalDocs attribute at other places. Thus yes the Core Team is welcome :)
@wing328
@jimschubert
@cbornet
@jmini
@etherealjoy
@spacether

welshm · 2022-12-05T15:11:53Z

modules/openapi-generator/src/main/resources/JavaSpring/api.mustache

@@ -16,6 +16,9 @@ import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import io.swagger.v3.oas.annotations.tags.Tag;
+{{#hasAuthMethods}}


Should this be #hasExternalDocs ?

Nice catch. I'll fix that.

…enerator : fix mustache template with #hasExternalDocs

…enerator: fix indentation

arey · 2022-12-05T17:12:16Z

Can you also regenerate the samples? Or do none of the samples have exeternal docs? If not, perhaps we should add one?

I'll we do that. For unit testing I've added an external docs to the petstore.yaml. So it should be present in the generated samples. May I have only generate the spring-boot-oas3.yaml config?

./bin/generate-samples.sh ./bin/configs/spring-boot-oas3.yaml

welshm · 2022-12-05T17:49:43Z

Can you also regenerate the samples? Or do none of the samples have exeternal docs? If not, perhaps we should add one?

I'll we do that. For unit testing I've added an external docs to the petstore.yaml. So it should be present in the generated samples. May I have only generate the spring-boot-oas3.yaml config?
./bin/generate-samples.sh ./bin/configs/spring-boot-oas3.yaml

You need to run all of the following:

  ./mvnw clean package 
  ./bin/generate-samples.sh
  ./bin/utils/export_docs_generators.sh

Otherwise tests will fail because the diffs won't match.

…enerator: fix carriage return

…enerator: regenerate the spring-boot-oas3.yaml sample

arey · 2022-12-05T18:13:27Z

I'll first generate the spring-boot-oas3. This could me fix some indentation and carriage return issues.
I will now regenerate all the samples.

arey · 2022-12-05T18:53:41Z

Generate all samples command looks like to failed on the master branch:

$ ./bin/generate-samples.sh ./bin/generate-samples.sh
...
[main] ERROR o.o.c.config.CodegenConfigurator - Unexpected character ('#' (code 35)): expected a valid value (JSON String, Number, Array, Object or token 'null', 'true' or 'false')
 at [Source: (File); line: 1, column: 2]
[main] ERROR o.o.c.config.CodegenConfigurator - Unexpected character ('#' (code 35)): expected a valid value (JSON String, Number, Array, Object or token 'null', 'true' or 'false')
 at [Source: (File); line: 1, column: 2]
Exception in thread "main" java.lang.RuntimeException: Unable to deserialize config file: ./bin/generate-samples.sh
        at org.openapitools.codegen.config.CodegenConfigurator.readDynamicSettings(CodegenConfigurator.java:167)
        at org.openapitools.codegen.config.CodegenConfigurator.fromFile(CodegenConfigurator.java:89)
        at org.openapitools.codegen.cmd.Generate.execute(Generate.java:293)
        at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
        at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

welshm · 2022-12-05T19:39:41Z

Generate all samples command looks like to failed on the master branch:

$ ./bin/generate-samples.sh ./bin/generate-samples.sh
...
[main] ERROR o.o.c.config.CodegenConfigurator - Unexpected character ('#' (code 35)): expected a valid value (JSON String, Number, Array, Object or token 'null', 'true' or 'false')
 at [Source: (File); line: 1, column: 2]
[main] ERROR o.o.c.config.CodegenConfigurator - Unexpected character ('#' (code 35)): expected a valid value (JSON String, Number, Array, Object or token 'null', 'true' or 'false')
 at [Source: (File); line: 1, column: 2]
Exception in thread "main" java.lang.RuntimeException: Unable to deserialize config file: ./bin/generate-samples.sh
        at org.openapitools.codegen.config.CodegenConfigurator.readDynamicSettings(CodegenConfigurator.java:167)
        at org.openapitools.codegen.config.CodegenConfigurator.fromFile(CodegenConfigurator.java:89)
        at org.openapitools.codegen.cmd.Generate.execute(Generate.java:293)
        at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
        at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

My guess is there's a serialized config file that needs to be updated because you added hasExternalDocs to the config.

…enerator: generate-samples.sh

arey · 2022-12-05T21:26:55Z

My guess is there's a serialized config file that needs to be updated because you added hasExternalDocs to the config.

Just a human error. I've generated then commited all the samples.
The export_docs_generators.sh does modified any files.

arey · 2022-12-12T08:30:02Z

Hi @welshm, do you know if the core team members could have a look on my change to to DefaultCodegen and CodegenOperation ?

welshm · 2022-12-12T12:08:36Z

Hi @welshm, do you know if the core team members could have a look on my change to to DefaultCodegen and CodegenOperation ?

I'll take another look today and then tag some of them

welshm · 2022-12-12T14:02:18Z

modules/openapi-generator/src/main/resources/JavaSpring/api.mustache

@@ -170,7 +173,8 @@ public interface {{classname}} {
            {{#authMethods}}
            @SecurityRequirement(name = "{{name}}"{{#isOAuth}}, scopes={ {{#scopes}}"{{scope}}"{{^-last}}, {{/-last}}{{/scopes}} }{{/isOAuth}}){{^-last}},{{/-last}}
            {{/authMethods}}
-        }{{/hasAuthMethods}}
+        }{{/hasAuthMethods}}{{#hasExternalDocs}},


Does this also work? I'm not an expert on mustache files, but I think you may not need the hasExternalDocs boolean if you check if the parameter externalDocs is set like this.

}{{/hasAuthMethods}}{{#externalDocs}}, externalDocs = @ExternalDocumentation(description = "{{externalDocs.description}}", url = "{{externalDocs.url}}") {{/externalDocs}}

For example, I see this in the Swift5 templates

{{#externalDocs}} - externalDocs: {{.}} {{/externalDocs}}

I didn't know the mustache syntax but it may work. I will check tomorrow.

I've removed the hasExternalDocs property. It's much simpler and the core classes are no more touched.

…enerator: remove hasExternalDocs

arey · 2022-12-16T09:25:49Z

Still don't know why the ci/circleci:node1 is failing: https://circleci.com/gh/OpenAPITools/openapi-generator/56336

Caused by: java.lang.UnsupportedClassVersionError: org/springframework/boot/maven/RepackageMojo has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 52.0

@welshm does it block my PR?

welshm · 2022-12-16T16:08:43Z

Still don't know why the ci/circleci:node1 is failing: https://circleci.com/gh/OpenAPITools/openapi-generator/56336
Caused by: java.lang.UnsupportedClassVersionError: org/springframework/boot/maven/RepackageMojo has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 52.0
@welshm does it block my PR?

Shouldn't block your PR

welshm

@wing328 will need to review and merge, but this looks great to me!

Thanks for adding the external docs!

wing328 · 2022-12-19T11:01:33Z

@arey thanks for the PR but some CI tests failed: https://github.com/OpenAPITools/openapi-generator/actions/runs/3680159465/jobs/6327983250

can you please take a look when you've time?

arey · 2022-12-21T11:02:46Z

Thanks for the review @wing328
It looks like the ExternalDocumentation java import is not generated. I will investigate.

…enerator: generate-samples.sh

arey · 2022-12-22T08:53:38Z

@wing328 I'll fixed the issue by systematically add the ExternalDocumentation java import (like others io.swagger.v3.oas.annotations.* imports).
I would have liked to make it conditional. But it requires that CodegenOperation shoud be aware of all the CodegenOperation. I don't know if other generators do this kind of import optimization?

arey · 2023-01-03T16:18:18Z

Any news?
I would like to known if it is possible to have this feature in the next 6.3.0 version?

arey · 2023-01-04T07:55:05Z

Thanks a lot William for this PR. And thank you for all the time you spent on this great project :)

OpenAPITools#14141 Add externalDocs to @operation to the JavaSpring g…

468e5da

…enerator

welshm reviewed Dec 5, 2022

View reviewed changes

arey added 2 commits December 5, 2022 16:53

OpenAPITools#14141 Add externalDocs to @operation to the JavaSpring g…

795b22b

…enerator : fix mustache template with #hasExternalDocs

OpenAPITools#14141 Add externalDocs to @operation to the JavaSpring g…

c90290f

…enerator: fix indentation

arey added 2 commits December 5, 2022 19:09

OpenAPITools#14141 Add externalDocs to @operation to the JavaSpring g…

f15dd2b

…enerator: fix carriage return

OpenAPITools#14141 Add externalDocs to @operation to the JavaSpring g…

328114d

…enerator: regenerate the spring-boot-oas3.yaml sample

OpenAPITools#14141 Add externalDocs to @operation to the JavaSpring g…

a06d0a8

…enerator: generate-samples.sh

welshm reviewed Dec 12, 2022

View reviewed changes

OpenAPITools#14141 Add externalDocs to @operation to the JavaSpring g…

819e33b

…enerator: remove hasExternalDocs

welshm approved these changes Dec 16, 2022

View reviewed changes

arey added 2 commits December 22, 2022 09:21

Fix ExternalDocumentation import generation and order

9f815f6

OpenAPITools#14141 Add externalDocs to @operation to the JavaSpring g…

8e61504

…enerator: generate-samples.sh

arey requested a review from welshm January 2, 2023 07:06

wing328 merged commit 917892d into OpenAPITools:master Jan 4, 2023

wing328 added the Enhancement: Feature label Jan 4, 2023

wing328 added Feature: Documentation Server: Spring labels Jan 4, 2023

wing328 added this to the 6.3.0 milestone Jan 4, 2023

wing328 changed the title ~~#14141 Add externalDocs to @Operation to the JavaSpring generator~~ Add externalDocs to @Operation to the JavaSpring generator Jan 4, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add externalDocs to @Operation to the JavaSpring generator #14177

Add externalDocs to @Operation to the JavaSpring generator #14177

arey commented Dec 5, 2022 •

edited

Loading

arey commented Dec 5, 2022

welshm left a comment

welshm Dec 5, 2022

arey Dec 5, 2022

welshm Dec 5, 2022

arey Dec 5, 2022

arey commented Dec 5, 2022

welshm commented Dec 5, 2022

arey commented Dec 5, 2022

arey commented Dec 5, 2022

welshm commented Dec 5, 2022

arey commented Dec 5, 2022

arey commented Dec 12, 2022

welshm commented Dec 12, 2022

welshm Dec 12, 2022

welshm Dec 12, 2022

arey Dec 12, 2022

arey Dec 12, 2022

arey commented Dec 16, 2022

welshm commented Dec 16, 2022

welshm left a comment

wing328 commented Dec 19, 2022

arey commented Dec 21, 2022

arey commented Dec 22, 2022

arey commented Jan 3, 2023 •

edited

Loading

arey commented Jan 4, 2023

Add externalDocs to @Operation to the JavaSpring generator #14177

Add externalDocs to @Operation to the JavaSpring generator #14177

Conversation

arey commented Dec 5, 2022 • edited Loading

PR checklist

arey commented Dec 5, 2022

welshm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

arey commented Dec 5, 2022

welshm commented Dec 5, 2022

arey commented Dec 5, 2022

arey commented Dec 5, 2022

welshm commented Dec 5, 2022

arey commented Dec 5, 2022

arey commented Dec 12, 2022

welshm commented Dec 12, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

arey commented Dec 16, 2022

welshm commented Dec 16, 2022

welshm left a comment

Choose a reason for hiding this comment

wing328 commented Dec 19, 2022

arey commented Dec 21, 2022

arey commented Dec 22, 2022

arey commented Jan 3, 2023 • edited Loading

arey commented Jan 4, 2023

arey commented Dec 5, 2022 •

edited

Loading

arey commented Jan 3, 2023 •

edited

Loading