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

cachescrubber · 2022-01-08T10:05:53Z

This PR introduces two new additional properties for all Java Based CodegenConfigs (extending AbstractJavaCodegen). The Properties are defined by a new Features interface, org.openapitools.codegen.languages.features.DocumentationProviderFeatures.

Synopsis

--additional-properties documentationProvider=springdoc,annotationLibrary=swagger2

When a documentation provider and annotation library are selected, a boolean property is added to the codegen model. For example, when SpringDoc is the selected as a documentation provider, the following properties are available in the mustache templates.

documentationProvider: springdoc
springDocDocumentationProvider: true
annotationLibrary: swagger2
swagger2AnnotationLibrary: true

The Documentation Provider and Annotation Libraries are defined in a dedicated Enum each.

My main goal is to define the property names used in the templates in a central location and to avoid having a dozen
of different additional property names and semantics in the various Java based CodegenConfigs.

The SpringCodegen serves as a demo of how to integrate into other Java based CodegenConfigs.

Naming is hard. The propertyNames and Annotation Values where not easy. Specially
Swagger1 and Swagger2 are based on the version numbers of their release artifacts, not using the target OAS specifiction version. Anyway, since the are defined in the Enums they are pretty easy to change in the current stage. Feel free to come up with suggestions and an alternative nameing.

Relates To

#8801
#9775
#11181

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.
Run the following to build the project and update samples:
```
./mvnw clean package 
./bin/generate-samples.sh
./bin/utils/export_docs_generators.sh
```
Commit all changed files.
This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
These must match the expectations made by your contribution.
You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
For Windows users, please run the script in Git BASH.
[x ] File the PR against the correct branch: master (5.3.0), 6.0.x
[ 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.

…avaCodegen

cachescrubber · 2022-01-08T10:14:34Z

@wing328 @welshm
@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)

This reverts commit a0d6aac.

cachescrubber · 2022-01-08T14:00:50Z

Docs and samples not updated yet - I'll wait for potential feedback and feasibility check.

welshm · 2022-01-08T14:15:17Z

Docs and samples not updated yet - I'll wait for potential feedback and feasibility check.

I'll try to take a look at this later today (EST)

cachescrubber · 2022-01-08T16:15:32Z

DocumentationProvider

Cli Option	Description	Property Name	Preferred Annotation Library	Supported Annotation Libraries
none	Do not publish an OpenAPI specification.	`withoutDocumentationProvider`	none	none, swagger1, swagger2, microprofile
source	Publish the original input OpenAPI specification.	`sourceDocumentationProvider`	none	none, swagger1, swagger2, microprofile
swagger1	Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using Swagger-Core 1.x.	`swagger1DocumentationProvider`	swagger1	swagger1
swagger2	Generate an OpenAPI 3 specification using Swagger-Core 2.x.	`swagger2DocumentationProvider`	swagger2	swagger2
springfox	Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x.	`springFoxDocumentationProvider`	swagger1	swagger1
springdoc	Generate an OpenAPI 3 specification using SpringDoc.	`springDocDocumentationProvider`	swagger2	swagger2

AnnotationLibrary

Cli Option	Description	Property Name
none	Do not annotate Model and Api with complementary annotations.	`withoutAnnotationLibrary`
swagger1	Annotate Model and Api using the Swagger Annotations 1.x library.	`swagger1AnnotationLibrary`
swagger2	Annotate Model and Api using the Swagger Annotations 2.x library.	`swagger2AnnotationLibrary`
microprofile	Annotate Model and Api using the Microprofile annotations.	`microprofileAnnotationLibrary`

cachescrubber · 2022-01-08T16:26:51Z

Output of config-help -g spring

       documentationProvider
            Select the OpenAPI documentation provider. (Default: springdoc)
                none - Do not publish an OpenAPI specification.
                source - Publish the original input OpenAPI specification.
                springfox - Generate a Swagger 2 specification using SpringFox 2.x.
                springdoc - Generate an OpenAPI 3 specification using SpringDoc.

        annotationLibrary
            Select the complementary documentation annotation library. (Default: auto)
                none - Do not annotate Model and Api with complementary annotations.
                swagger1 - Annotate Model and Api using the Swagger Annotations 1.x library.
                swagger2 - Annotate Model and Api using the Swagger Annotations 2.x library.

.../openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java

welshm · 2022-01-10T15:15:57Z

...pi-generator/src/main/resources/JavaSpring/libraries/spring-boot/openapi2SpringBoot.mustache

@@ -63,13 +63,13 @@ public class OpenAPI2SpringBoot implements CommandLineRunner {
                        .allowedMethods("*")
                        .allowedHeaders("Content-Type");
            }*/
-{{^useSpringfox}}
+{{^springFoxDocumentationProvider}}


Is this the right check? Or is the resource handler needed for specific non-Springfox providers?

I just replaced the template variable name - not the logic

Hmmm... I suspect this will cause issues with some configurations but we can find out later

welshm · 2022-01-10T15:18:15Z

...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java

+      NONE("withoutDocumentationProvider", "Do not publish an OpenAPI specification.",
+          AnnotationLibrary.NONE, AnnotationLibrary.values()),
+
+      SOURCE("sourceDocumentationProvider", "Publish the original input OpenAPI specification.",
+          AnnotationLibrary.NONE, AnnotationLibrary.values()),
+
+      SWAGGER1("swagger1DocumentationProvider", "Generate a Swagger 2 specification using Swagger-Core 1.x.",
+          AnnotationLibrary.SWAGGER1, AnnotationLibrary.SWAGGER1),
+
+      SWAGGER2("swagger2DocumentationProvider", "Generate an OpenAPI 3 specification using Swagger-Core 2.x.",
+          AnnotationLibrary.SWAGGER2, AnnotationLibrary.SWAGGER2),
+


Is the plan to add support for these providers before submitting this PR?

No - at least not in the spring generator. General Idea ist that other generators should use the same cli options and template variables to make the project easier to maintain in the long run.

If it is decided to make it spring generator only, I would probably remove those Enum values.

...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java

# Conflicts: # modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java # modules/openapi-generator/src/main/resources/JavaSpring/api.mustache # modules/openapi-generator/src/main/resources/JavaSpring/apiController.mustache # modules/openapi-generator/src/main/resources/JavaSpring/pojo.mustache

cachescrubber · 2022-01-17T15:04:42Z

I merged in master and resolved conflicts after #11229.

This time I actually changed the sample configs and generated all samples.

All issues detected by the samples builds are resolved.

New: @ParameterObject support (SpringDoc feature to support spring-data Pageable).

…nstead of just "Swagger"

wing328 · 2022-01-19T16:45:37Z

diff --git a/docs/generators/java-camel.md b/docs/generators/java-camel.md
index a55d98db..4c8768c9 100644
--- a/docs/generators/java-camel.md
+++ b/docs/generators/java-camel.md
@@ -20,6 +20,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |additionalEnumTypeAnnotations|Additional annotations for enum type(class level annotations)| |null|
 |additionalModelTypeAnnotations|Additional annotations for model type(class level annotations). List separated by semicolon(;) or new line (Linux or Windows)| |null|
 |allowUnicodeIdentifiers|boolean, toggles whether unicode identifiers are allowed in names or not, default is false| |false|
+|annotationLibrary|Select the complementary documentation annotation library.|<dl><dt>**none**</dt><dd>Do not annotate Model and Api with complementary annotations.</dd><dt>**swagger1**</dt><dd>Annotate Model and Api using the Swagger Annotations 1.x library.</dd><dt>**swagger2**</dt><dd>Annotate Model and Api using the Swagger Annotations 2.x library.</dd></dl>|swagger2|
 |apiFirst|Generate the API from the OAI spec at server compile time (API first approach)| |false|
 |apiPackage|package for generated api classes| |org.openapitools.api|
 |artifactDescription|artifact description in generated pom.xml| |OpenAPI Java|
@@ -47,6 +48,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |disableHtmlEscaping|Disable HTML escaping of JSON strings when using gson (needed to avoid problems with byte[] fields)| |false|
 |disallowAdditionalPropertiesIfNotPresent|If false, the 'additionalProperties' implementation (set to true by default) is compliant with the OAS and JSON schema specifications. If true (default), keep the old (incorrect) behaviour that 'additionalProperties' is set to false by default.|<dl><dt>**false**</dt><dd>The 'additionalProperties' implementation is compliant with the OAS and JSON schema specifications.</dd><dt>**true**</dt><dd>Keep the old (incorrect) behaviour that 'additionalProperties' is set to false by default.</dd></dl>|true|
 |discriminatorCaseSensitive|Whether the discriminator value lookup should be case-sensitive or not. This option only works for Java API client| |true|
+|documentationProvider|Select the OpenAPI documentation provider.|<dl><dt>**none**</dt><dd>Do not publish an OpenAPI specification.</dd><dt>**source**</dt><dd>Publish the original input OpenAPI specification.</dd><dt>**springfox**</dt><dd>Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x.</dd><dt>**springdoc**</dt><dd>Generate an OpenAPI 3 specification using SpringDoc.</dd></dl>|springdoc|

as reported by https://github.com/OpenAPITools/openapi-generator/runs/4866174156?check_suite_focus=true

Can you please repeat step 3 to have the doc updated? Thanks.

cachescrubber · 2022-01-19T17:07:11Z

@wing328 I run export_docs_generators.sh and pushed the changes.

wing328 · 2022-01-22T00:53:38Z

@cachescrubber thanks again for the PR, which has been merged.

When you've time next week, can you please PM me via Slack? https://join.slack.com/t/openapi-generator/shared_invite/enQtNzAyNDMyOTU0OTE1LTY5ZDBiNDI5NzI5ZjQ1Y2E5OWVjMjZkYzY1ZGM2MWQ4YWFjMzcyNDY5MGI4NjQxNDBiMTlmZTc5NjY2ZTQ5MGM

cdprete · 2022-01-30T18:03:26Z

Hi.
Is this implemented in the latest version (5.3.1)?

I'm trying to set, from Maven, annotationLibrary to none as documented at https://openapi-generator.tech/docs/generators/spring, but Swagger annotations are still added to the generated models.

cachescrubber added 3 commits January 8, 2022 10:34

Implement DocumentationProviderFeatures and integrate it in AbstractJ…

9865887

…avaCodegen

Integrate DocumentationProviderFeatures in SpringCodegen

4fc7f38

Run new test config spring-boot-springdoc

7d11e76

cachescrubber mentioned this pull request Jan 8, 2022

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

Closed

5 tasks

cachescrubber added 5 commits January 8, 2022 13:14

Do not use Locale.ROOT

a0d6aac

Do not use Locale.ROOT, use NONE instead of empty list

e9fc691

Revert "Do not use Locale.ROOT"

55679cc

This reverts commit a0d6aac.

Do not use forbidden APIs

511afee

Fix spring maven plugin example

e9c5f7d

cachescrubber requested a review from jimschubert as a code owner January 8, 2022 13:47

cachescrubber added 3 commits January 8, 2022 17:27

Introduce DocumentationProviderFeaturesTest.java

b7160a1

replace AUTO with preferredAnnotationLibrary

75a722c

remove sout.println from Test

4aaec1d

cachescrubber force-pushed the feature/documentation_provider_pr branch from 0320e69 to 4aaec1d Compare January 9, 2022 09:15

welshm reviewed Jan 10, 2022

View reviewed changes

Apply code style.

6545e41

wing328 added Enhancement: New generator Server: Spring labels Jan 16, 2022

wing328 added this to the 5.4.0 milestone Jan 16, 2022

cachescrubber added 6 commits January 17, 2022 12:17

Update spring sample configuration to use the new property

fa103a5

Update samples after merge

508665b

fix atBean import

cb2e80c

Generate all samples

b998d34

Add ParameterObject to test

f1e6108

cachescrubber added 2 commits January 17, 2022 16:26

Allow Subclasses to opt out

649843a

Use OpenAPI 2 (fka Swagger RESTful API Documentation Specification) i…

34411e8

…nstead of just "Swagger"

export generator docs

71c80b0

cachescrubber added 2 commits January 19, 2022 19:09

Fix typo

c627c09

Fix typo - update docs.

f171ace

cachescrubber mentioned this pull request Jan 21, 2022

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

Open

6 tasks

wing328 merged commit e1c5b22 into OpenAPITools:master Jan 22, 2022

cachescrubber deleted the feature/documentation_provider_pr branch January 22, 2022 10:44

This was referenced Jan 30, 2022

[Java/Spring] Revert to fully qualified import for org.springframework.core.io.Resource #11461

Merged

Implement Source DocumentationProvider, spring-mvc decommission #11531

Merged

sjoblomj mentioned this pull request Apr 20, 2022

[kotlin-spring] Adding DocumentationProvider and SwaggerUI #12184

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

cachescrubber commented Jan 8, 2022 •

edited

Loading

cachescrubber commented Jan 8, 2022

cachescrubber commented Jan 8, 2022

welshm commented Jan 8, 2022

cachescrubber commented Jan 8, 2022 •

edited

Loading

cachescrubber commented Jan 8, 2022

welshm Jan 10, 2022

cachescrubber Jan 10, 2022

welshm Jan 11, 2022

welshm Jan 10, 2022

cachescrubber Jan 10, 2022

cachescrubber commented Jan 17, 2022

wing328 commented Jan 19, 2022

cachescrubber commented Jan 19, 2022

wing328 commented Jan 22, 2022 •

edited

Loading

cdprete commented Jan 30, 2022 •

edited

Loading

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

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

Conversation

cachescrubber commented Jan 8, 2022 • edited Loading

Synopsis

PR checklist

cachescrubber commented Jan 8, 2022

cachescrubber commented Jan 8, 2022

welshm commented Jan 8, 2022

cachescrubber commented Jan 8, 2022 • edited Loading

DocumentationProvider

AnnotationLibrary

cachescrubber commented Jan 8, 2022

welshm Jan 10, 2022

Choose a reason for hiding this comment

cachescrubber Jan 10, 2022

Choose a reason for hiding this comment

welshm Jan 11, 2022

Choose a reason for hiding this comment

welshm Jan 10, 2022

Choose a reason for hiding this comment

cachescrubber Jan 10, 2022

Choose a reason for hiding this comment

cachescrubber commented Jan 17, 2022

wing328 commented Jan 19, 2022

cachescrubber commented Jan 19, 2022

wing328 commented Jan 22, 2022 • edited Loading

cdprete commented Jan 30, 2022 • edited Loading

cachescrubber commented Jan 8, 2022 •

edited

Loading

cachescrubber commented Jan 8, 2022 •

edited

Loading

wing328 commented Jan 22, 2022 •

edited

Loading

cdprete commented Jan 30, 2022 •

edited

Loading