Allow Spring generated code to use new OAS 3 annotations by welshm · Pull Request #9775 · OpenAPITools/openapi-generator

welshm · 2021-06-15T18:45:23Z

Add in oas3 option for Spring codegen to use newer annotations
Add useSpringController option for Spring codegen
Use useSpringfox to fix some unwanted imports for Spring codegen
Use jdk8 to add OffsetDateTime import for models in Spring codegen
Add JsonValue to enumOuterClass.mustache to allow enums to be
generated properly
To test, use oas3: true useSpringController: true and useSpringfox: false in a config file to generate a Spring target.

To close #9774

PR checklist

Read the contribution guidelines.
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.

Run the following to build the project and update samples:

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

File the PR against the correct branch: master, 5.1.x, 6.0.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.

- Add in `oas3` option for Spring codegen to use newer annotations - Add `useSpringController` option for Spring codegen - Use `useSpringfox` to fix some unwanted imports for Spring codegen - Use `jdk8` to add OffsetDateTime import for models in Spring codegen - Add `JsonValue` to `enumOuterClass.mustache` to allow enums to be generated properly

Bring `welshm` fork up to master

welshm · 2021-06-15T18:52:00Z

I think @diyfr and @nmuesch might be good reviewers for this?

ritual-nik · 2021-06-15T19:04:02Z

-        if (!this.apiFirst && !this.reactive) {
-            additionalProperties.put("useSpringfox", true);
+        if (this.useSpringfox) {
+            if (!this.apiFirst && !this.reactive) {


minor, can simplify to: this.useSpringFox && !this.apiFirst && !this.reactive

I'll add comments - I assume that springFox cannot be used when apiFirst and reactive is enabled but we don't use those options so I wanted it to be clear that this check is separate from the useSpringFox option check

welshm · 2021-06-21T15:24:24Z

@daonomic or @lwlee2608 Would you be an appropriate reviewer for this?

welshm · 2021-06-29T13:58:34Z

@wing328 - wondering if you can help me find an appropriate reviewer or how I might go about getting this added?

welshm · 2021-07-12T20:48:57Z

@4brunu Would you be able to help me get a review started on this? I have not had responses from anyone else so far

4brunu · 2021-07-12T21:02:42Z

You need to copy the java technical committee members for review.

@bbdouglas (2017/07) @sreeshas (2017/08) @jfiala (2017/08) @lukoyanov (2017/09) @cbornet (2017/09) @jeff9finger (2018/01) @karismann (2019/03) @Zomzog (2019/04) @lwlee2608 (2019/10) @nmuesch (2021/01)

welshm · 2021-07-15T16:38:18Z

I'm happy to join or participate in a technical committee if that might help...

welshm · 2021-07-26T14:06:20Z

@4brunu do you happen to know what the expected response time is for opening a PR and receiving a review or for applying for the technical commmittee?

Part of wanting to contribute back is so that my organization doesn't diverge too much from the project here, but it's now been over a month with no response to opening the PR other than from yourself...

wing328 · 2021-07-26T15:45:47Z

Let me try to take a look tomorrow or later this week.

welshm · 2021-07-30T14:52:37Z

Let me try to take a look tomorrow or later this week.

Just following up here - I will be unavailalbe Aug 3 - 6 if there is feedback on this PR.

I am very much interested in joining the technical committee for Spring and Java if you're taking applicants (I did send an email) in order to help keep the generator supported for those languages.

Bring `welshm` fork up to `OpenAPITools` master

welshm · 2021-08-06T13:50:31Z

@wing328 any chance to get this reviewed?

…nerator into allow_oas3_annotations

welshm · 2021-08-23T14:44:38Z

@wing328 Updated with latest master and regenerated tests/samples

MichaelKunze · 2021-08-25T14:31:58Z

Would be cool if this PR gets considered! Need this too.

welshm · 2021-09-01T14:26:36Z

@wing328 @4brunu is there anything more I can do to get this reviewed or looked at by someone on the team that can approve this?

This PR has been open for 2+ months, and I've kept it current with the main branch several times, but if no one will review it then there is no value in me maintaining this branch/PR.

I am more than happy to get more involved in the project, but my emails asking to join the team have also gone unanswered.

InfoSec812 · 2021-10-26T14:51:50Z

Functionally, I think this is quite good. I would like to see future improvements to readability as time permits. I think it would be nice to break out the OAS3/Swagger annotations into separate sub-templates which get included conditionally so that there isn't quite so much noise.

I'd be more than happy to tackle that - do you have an example or time for a quick discussion on what you imagine the file structure would look like (e.g. a separate file for Swagger2 vs. OAS3 each for boot/mvc/cloud? I could see a lot of repetition occurring there as some options (Java8, async, etc.) apply to both.

Definitely learned a lot with this PR and will definitely look to be more thorough in testing further PRs. Some of the mustache's are not features I am currently using so getting familiar with it all.

@welshm HERE is an example where the generatedAnnotation is coming from an included template. I don't think it's necessary for this PR, but it would be nice later to make things more readable/maintainable.

welshm · 2021-10-29T14:04:33Z

Functionally, I think this is quite good. I would like to see future improvements to readability as time permits. I think it would be nice to break out the OAS3/Swagger annotations into separate sub-templates which get included conditionally so that there isn't quite so much noise.

I'd be more than happy to tackle that - do you have an example or time for a quick discussion on what you imagine the file structure would look like (e.g. a separate file for Swagger2 vs. OAS3 each for boot/mvc/cloud? I could see a lot of repetition occurring there as some options (Java8, async, etc.) apply to both.
Definitely learned a lot with this PR and will definitely look to be more thorough in testing further PRs. Some of the mustache's are not features I am currently using so getting familiar with it all.

@welshm HERE is an example where the generatedAnnotation is coming from an included template. I don't think it's necessary for this PR, but it would be nice later to make things more readable/maintainable.

I'd love to keep making improvements for Spring support (Java and eventually Kotlin) so I'll look to make some of those changes in a future PR

wing328 · 2021-11-02T16:44:50Z

Did a few more tests and the results are good so let's merge this one and file separate PRs for enhancements if needed.

atkawa7 · 2021-11-02T16:58:03Z

@wing328 would you be able to do a minor release to test this out

wing328 · 2021-11-03T03:41:54Z

@atkawa7 can you please use the SNAPSHOT version (links in the readme) before v5.3.1 release (which is scheduled a month later)?

atkawa7 · 2021-11-03T20:40:23Z

Thanks @wing328

mhinders · 2021-12-17T09:08:36Z

Really happy about this change. I would however be inclined to use springdocs for viewing the API definition. As it is currently the Spring controllers are generated with @org.springframework.stereotype.Controller and not @org.springframework.web.bind.annotation.RestController which means that manual configuration is required as explained here https://springdoc.org/#my-rest-controller-using-controller-annotation-is-ignored. Could the templates be changed to use RestController?

welshm · 2021-12-17T15:40:39Z

Really happy about this change. I would however be inclined to use springdocs for viewing the API definition. As it is currently the Spring controllers are generated with @org.springframework.stereotype.Controller and not @org.springframework.web.bind.annotation.RestController which means that manual configuration is required as explained here https://springdoc.org/#my-rest-controller-using-controller-annotation-is-ignored. Could the templates be changed to use RestController?

It can be updated to do that - just for clarity though, I had added this as an option for the interfaces but had left the generated API controller implementations (apiController.mustache) unchanged - would you be expecting both to be annotated with @RestController? My opinion is probably not, as the interface has all the annotations you need.

BlackSunshine-manage · 2021-12-22T21:37:07Z

Hello! how i can use this plugin?? this is a big work and i waited to long time this. You're really cool!

Jey2k · 2021-12-23T10:56:44Z

Hi,
Quite a noob in this part, but I'm currently trying to migrate one of our application and I would like to use this generator. So first thanks for your work.
The last problem detected is with "oas3" activated, and a default value on a query param it gives some code not compatible with Swagger v3 annotations:
eg:
,@Parameter(name = "size", description = "Size of the results page (maximum size is 1'000)", defaultValue = "1000") @RequestParam(value = "size", required = false, defaultValue = "1000") Integer size

I suppose it should be included into @Schema, isn't it ?
eg:
,@Parameter(name = "size", description = "Size of the results page (maximum size is 1'000)", schema = @Schema( defaultValue = "1000" )) @RequestParam(value = "size", required = false, defaultValue = "1000") Integer size

marinus-suniram · 2021-12-29T19:08:59Z

I have the same problem with the default value

welshm · 2021-12-29T19:16:06Z

Please see this change #11181 from @cachescrubber which is addressing the issues of default params and Schema (along with other issues)

kdebski85 · 2021-12-30T14:03:46Z

I also have the issue with defaultValue for Parameter. I created #11203

mhinders · 2022-01-03T13:04:55Z

Really happy about this change. I would however be inclined to use springdocs for viewing the API definition. As it is currently the Spring controllers are generated with @org.springframework.stereotype.Controller and not @org.springframework.web.bind.annotation.RestController which means that manual configuration is required as explained here https://springdoc.org/#my-rest-controller-using-controller-annotation-is-ignored. Could the templates be changed to use RestController?

It can be updated to do that - just for clarity though, I had added this as an option for the interfaces but had left the generated API controller implementations (apiController.mustache) unchanged - would you be expecting both to be annotated with @RestController? My opinion is probably not, as the interface has all the annotations you need.

I missed that the annotation is present on the interface. That is sufficient for me.

shivaprasadgurram · 2022-07-15T09:39:43Z

springdoc-openapi-ui not compatible with openapi-generator-maven-plugin. I have a dependency of spring-openapi-ui with version 1.6.9. I can see generated classes are using V3 annotations but when I try to load swagger-ui.html it is not working. Not sure what is going wrong. Can any one help me?

Need: I should be able to open swagger-ui page from browser.

Moonergfp · 2023-06-12T08:35:41Z

springdoc-openapi-ui not compatible with openapi-generator-maven-plugin. I have a dependency of spring-openapi-ui with version 1.6.9. I can see generated classes are using V3 annotations but when I try to load swagger-ui.html it is not working. Not sure what is going wrong. Can any one help me?

Need: I should be able to open swagger-ui page from browser.

what would be shown when you open swagger-ui page?

welshm and others added 3 commits June 15, 2021 14:23

Merge pull request #1 from OpenAPITools/master

2d68708

Bring `welshm` fork up to master

Update spring examples

e7919ce

Merge branch 'master' into allow_oas3_annotations

baaa0e3

ritual-nik reviewed Jun 15, 2021

View reviewed changes

welshm added 2 commits June 15, 2021 15:47

Update with a clean maven install and regenerate samples

40e09bc

Remove newling at end of param files and regenerate samples

b603d34

welshm and others added 3 commits July 30, 2021 09:13

Merge pull request #5 from OpenAPITools/master

a3d03bb

Bring `welshm` fork up to `OpenAPITools` master

Merge branch 'master' into allow_oas3_annotations

31fcabf

Update codegen with merge from master

169ce75

welshm mentioned this pull request Aug 6, 2021

[REQ][Java][Spring] Allow Spring generated code to use new OAS 3 annotations #9774

Closed

welshm added 4 commits August 23, 2021 09:56

Merge branch 'master' of github.com:OpenAPITools/openapi-generator

8c30649

Merge branch 'master' into allow_oas3_annotations

ef35531

Update tests and samples

8b45b76

Merge branch 'allow_oas3_annotations' of github.com:welshm/openapi-ge…

c531860

…nerator into allow_oas3_annotations

welshm added 2 commits August 23, 2021 10:49

Remove #vendorParams from API

c4d9aaa

Update generated and tests

2e55e97

wing328 merged commit b117d29 into OpenAPITools:master Nov 2, 2021

welshm deleted the allow_oas3_annotations branch November 3, 2021 01:22

baurceanu mentioned this pull request Nov 15, 2021

[REQ] Generate classes with Swagger 3 (OpenAPI) annotations #10814

Closed

welshm restored the allow_oas3_annotations branch November 19, 2021 18:17

welshm deleted the allow_oas3_annotations branch November 19, 2021 18:19

WIStudent mentioned this pull request Dec 1, 2021

[BUG] [spring] Request Body is not parsed correctly when using oas3 option #11007

Closed

6 tasks

welshm mentioned this pull request Dec 10, 2021

Moved to Swagger 2 annotations as well as SpringDoc instead of Springfox #4779

Closed

wing328 added this to the 5.3.1 milestone Dec 18, 2021

cachescrubber mentioned this pull request Dec 23, 2021

[Java Spring OAS3] Fix numerous OAS3 related Bugs #11181

Merged

1 task

This was referenced Jan 4, 2022

[Java][Client] Add CLI option to select OpenAPI annotation library #8801

Closed

[JAVA] new Feature interface: Documentation Provider and Annotation Library #11258

Merged

eguller mentioned this pull request Jan 12, 2022

[REQ] Is it possible to use swagger 3 annotation in place of swagger 2 for java? #6108

Open

kevinparaport mentioned this pull request Jan 21, 2022

[BUG] [JAVA] OAS3 incorrect data type when providing a default value #11367

Open

6 tasks

tofi86 mentioned this pull request Feb 9, 2022

Fix for multible tags in @Operation annotation #11475

Merged

5 tasks

Uh oh!

Conversation

welshm commented Jun 15, 2021 • edited by wing328 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR checklist

Uh oh!

welshm commented Jun 15, 2021

Uh oh!

ritual-nik Jun 15, 2021

Choose a reason for hiding this comment

Uh oh!

welshm Jun 15, 2021

Choose a reason for hiding this comment

Uh oh!

welshm commented Jun 21, 2021

Uh oh!

welshm commented Jun 29, 2021

Uh oh!

welshm commented Jul 12, 2021

Uh oh!

4brunu commented Jul 12, 2021

Uh oh!

welshm commented Jul 15, 2021

Uh oh!

welshm commented Jul 26, 2021

Uh oh!

wing328 commented Jul 26, 2021

Uh oh!

welshm commented Jul 30, 2021

Uh oh!

welshm commented Aug 6, 2021

Uh oh!

welshm commented Aug 23, 2021

Uh oh!

MichaelKunze commented Aug 25, 2021

Uh oh!

welshm commented Sep 1, 2021

Uh oh!

InfoSec812 commented Oct 26, 2021

Uh oh!

welshm commented Oct 29, 2021

Uh oh!

wing328 commented Nov 2, 2021

Uh oh!

atkawa7 commented Nov 2, 2021

Uh oh!

wing328 commented Nov 3, 2021

Uh oh!

atkawa7 commented Nov 3, 2021

Uh oh!

mhinders commented Dec 17, 2021

Uh oh!

welshm commented Dec 17, 2021

Uh oh!

BlackSunshine-manage commented Dec 22, 2021

Uh oh!

Jey2k commented Dec 23, 2021

Uh oh!

marinus-suniram commented Dec 29, 2021

Uh oh!

welshm commented Dec 29, 2021

Uh oh!

kdebski85 commented Dec 30, 2021

Uh oh!

mhinders commented Jan 3, 2022

Uh oh!

shivaprasadgurram commented Jul 15, 2022

Uh oh!

Moonergfp commented Jun 12, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

14 participants

welshm commented Jun 15, 2021 •

edited by wing328

Loading