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

Merged
wing328 merged 23 commits into
OpenAPITools:masterfrom
cachescrubber:feature/documentation_provider_pr
Jan 22, 2022
Merged

[JAVA] new Feature interface: Documentation Provider and Annotation Library#11258
wing328 merged 23 commits into
OpenAPITools:masterfrom
cachescrubber:feature/documentation_provider_pr

Conversation

@cachescrubber

@cachescrubbercachescrubber commented Jan 8, 2022•
edited
Loading

Copy link
Copy Markdown
Contributor

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.

@cachescrubbercachescrubber mentioned this pull request Jan 8, 2022
Closed
5 tasks
@cachescrubber

cachescrubber commented Jan 8, 2022

Copy link
Copy Markdown
ContributorAuthor

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

@cachescrubber

cachescrubber commented Jan 8, 2022

Copy link
Copy Markdown
ContributorAuthor

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

@welshm

welshm commented Jan 8, 2022

Copy link
Copy Markdown
Contributor

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

cachescrubber commented Jan 8, 2022•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

DocumentationProvider

Cli OptionDescriptionProperty NamePreferred Annotation LibrarySupported Annotation Libraries
noneDo not publish an OpenAPI specification.withoutDocumentationProvidernonenone, swagger1, swagger2, microprofile
sourcePublish the original input OpenAPI specification.sourceDocumentationProvidernonenone, swagger1, swagger2, microprofile
swagger1Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using Swagger-Core 1.x.swagger1DocumentationProviderswagger1swagger1
swagger2Generate an OpenAPI 3 specification using Swagger-Core 2.x.swagger2DocumentationProviderswagger2swagger2
springfoxGenerate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x.springFoxDocumentationProviderswagger1swagger1
springdocGenerate an OpenAPI 3 specification using SpringDoc.springDocDocumentationProviderswagger2swagger2

AnnotationLibrary

Cli OptionDescriptionProperty Name
noneDo not annotate Model and Api with complementary annotations.withoutAnnotationLibrary
swagger1Annotate Model and Api using the Swagger Annotations 1.x library.swagger1AnnotationLibrary
swagger2Annotate Model and Api using the Swagger Annotations 2.x library.swagger2AnnotationLibrary
microprofileAnnotate Model and Api using the Microprofile annotations.microprofileAnnotationLibrary

@cachescrubber

cachescrubber commented Jan 8, 2022

Copy link
Copy Markdown
ContributorAuthor

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.

@cachescrubber
cachescrubberforce-pushed the feature/documentation_provider_pr branch from 0320e69 to 4aaec1dCompareJanuary 9, 2022 09:15
welshm
welshm reviewed Jan 10, 2022
View reviewed changes
Comment thread.../openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java Outdated
Comment thread...pi-generator/src/main/resources/JavaSpring/libraries/spring-boot/openapi2SpringBoot.mustache
.allowedHeaders("Content-Type");
}*/
{{^useSpringfox}}
{{^springFoxDocumentationProvider}}

@welshmwelshmJan 10, 2022

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@cachescrubbercachescrubberJan 10, 2022

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just replaced the template variable name - not the logic

@welshmwelshmJan 11, 2022

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java
Comment on lines +62 to +73
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),

@welshmwelshmJan 10, 2022

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@cachescrubbercachescrubberJan 10, 2022

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java Outdated
@wing328wing328 added this to the 5.4.0 milestone Jan 16, 2022
@cachescrubber
Merge branch 'master' into feature/documentation_provider_pr
ace2182
# 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
Update spring sample configuration to use the new property
fa103a5
@cachescrubber
Update samples after merge
508665b
@cachescrubber
fix atBean import
cb2e80c
@cachescrubber
Generate all samples
b998d34
@cachescrubber
Add ParameterObject to test
f1e6108
@cachescrubber

cachescrubber commented Jan 17, 2022

Copy link
Copy Markdown
ContributorAuthor

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).

@wing328

wing328 commented Jan 19, 2022

Copy link
Copy Markdown
Member
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

cachescrubber commented Jan 19, 2022

Copy link
Copy Markdown
ContributorAuthor

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

@cachescrubbercachescrubber mentioned this pull request Jan 21, 2022
Open
6 tasks
@wing328
wing328 merged commit e1c5b22 into OpenAPITools:masterJan 22, 2022
@wing328

wing328 commented Jan 22, 2022•
edited
Loading

Copy link
Copy Markdown
Member

@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

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

cdprete commented Jan 30, 2022•
edited
Loading

Copy link
Copy Markdown

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.

This was referenced Jan 30, 2022
Merged
Merged
@sjoblomjsjoblomj mentioned this pull request Apr 20, 2022
Merged
4 tasks
@cgual206cgual206 mentioned this pull request Aug 5, 2025
Merged
6 tasks
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@wing328wing328wing328 left review comments
@jimschubertjimschubertAwaiting requested review from jimschubert
+1 more reviewer
@welshmwelshmwelshm left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

Enhancement: New generatorServer: Spring

Projects

None yet

Milestone

5.4.0

Development

Successfully merging this pull request may close these issues.

4 participants

@cachescrubber@welshm@wing328@cdprete
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
[JAVA] new Feature interface: Documentation Provider and Annotation Library - #11258
Merged
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Jan 22, 2022
Merged
[JAVA] new Feature interface: Documentation Provider and Annotation Library#11258
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Conversation
@cachescrubber
@cachescrubbercachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

Contributor
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.
@cachescrubbercachescrubber
mentioned this pull request
Jan 8, 2022
 Closed

5 tasks
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
@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)
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
Docs and samples not updated yet - I'll wait for potential feedback and feasibility check.
@welshm
welshm
commented
Jan 8, 2022

Copy link


Copy Markdown

Contributor
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
cachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
DocumentationProvider
Cli OptionDescriptionProperty NamePreferred Annotation LibrarySupported Annotation Libraries
noneDo not publish an OpenAPI specification.withoutDocumentationProvidernonenone, swagger1, swagger2, microprofile
sourcePublish the original input OpenAPI specification.sourceDocumentationProvidernonenone, swagger1, swagger2, microprofile
swagger1Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using Swagger-Core 1.x.swagger1DocumentationProviderswagger1swagger1
swagger2Generate an OpenAPI 3 specification using Swagger-Core 2.x.swagger2DocumentationProviderswagger2swagger2
springfoxGenerate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x.springFoxDocumentationProviderswagger1swagger1
springdocGenerate an OpenAPI 3 specification using SpringDoc.springDocDocumentationProviderswagger2swagger2
AnnotationLibrary
Cli OptionDescriptionProperty Name
noneDo not annotate Model and Api with complementary annotations.withoutAnnotationLibrary
swagger1Annotate Model and Api using the Swagger Annotations 1.x library.swagger1AnnotationLibrary
swagger2Annotate Model and Api using the Swagger Annotations 2.x library.swagger2AnnotationLibrary
microprofileAnnotate Model and Api using the Microprofile annotations.microprofileAnnotationLibrary
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
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.

@cachescrubber
cachescrubberforce-pushed
the
feature/documentation_provider_pr
branch
from
0320e69 to
4aaec1dCompareJanuary 9, 2022 09:15
welshm
welshm
reviewed
Jan 10, 2022
View reviewed changes
Comment thread.../openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java
Outdated

Comment thread...pi-generator/src/main/resources/JavaSpring/libraries/spring-boot/openapi2SpringBoot.mustache
 .allowedHeaders("Content-Type");
 }*/
{{^useSpringfox}}
{{^springFoxDocumentationProvider}}
@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the right check? Or is the resource handler needed for specific non-Springfox providers?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just replaced the template variable name - not the logic
@welshmwelshmJan 11, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm... I suspect this will cause issues with some configurations but we can find out later
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java

Comment on lines

+62
 to 
+73

 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),

@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the plan to add support for these providers before submitting this PR?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java
Outdated

@wing328wing328
added this to the 5.4.0 milestone
Jan 16, 2022
@cachescrubber
Merge branch 'master' into feature/documentation_provider_pr
ace2182
# 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
Update spring sample configuration to use the new property
fa103a5
@cachescrubber
Update samples after merge
508665b
@cachescrubber
fix atBean import
cb2e80c
@cachescrubber
Generate all samples
b998d34
@cachescrubber
Add ParameterObject to test
f1e6108
@cachescrubber
cachescrubber
commented
Jan 17, 2022

Copy link


Copy Markdown

ContributorAuthor
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).
@wing328
wing328
commented
Jan 19, 2022

Copy link


Copy Markdown

Member
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
cachescrubber
commented
Jan 19, 2022

Copy link


Copy Markdown

ContributorAuthor
@wing328 I run export_docs_generators.sh and pushed the changes.
@cachescrubbercachescrubber
mentioned this pull request
Jan 21, 2022

Open

6 tasks
@wing328
wing328
merged commit e1c5b22
into
OpenAPITools:masterJan 22, 2022
@wing328
wing328
commented
Jan 22, 2022•

edited

Loading

Copy link


Copy Markdown

Member
@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
@cachescrubber
cachescrubber
deleted the

feature/documentation_provider_pr

branch
January 22, 2022 10:44
@cdprete
cdprete
commented
Jan 30, 2022•

edited

Loading

Copy link


Copy Markdown

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.

This was referenced Jan 30, 2022
 Merged

 Merged

@sjoblomjsjoblomj
mentioned this pull request
Apr 20, 2022
 Merged

4 tasks
@cgual206cgual206
mentioned this pull request
Aug 5, 2025
 Merged

6 tasks
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@wing328wing328wing328 left review comments
@jimschubertjimschubertAwaiting requested review from jimschubert

+1 more reviewer

@welshmwelshmwelshm left review comments
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

Enhancement: New generatorServer: Spring

Projects


None yet


Milestone

5.4.0

Development

Successfully merging this pull request may close these issues.

4 participants

@cachescrubber@welshm@wing328@cdprete

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
[JAVA] new Feature interface: Documentation Provider and Annotation Library - #11258
Merged
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Jan 22, 2022
Merged
[JAVA] new Feature interface: Documentation Provider and Annotation Library#11258
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Conversation
@cachescrubber
@cachescrubbercachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

Contributor
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.
@cachescrubbercachescrubber
mentioned this pull request
Jan 8, 2022
 Closed

5 tasks
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
@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)
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
Docs and samples not updated yet - I'll wait for potential feedback and feasibility check.
@welshm
welshm
commented
Jan 8, 2022

Copy link


Copy Markdown

Contributor
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
cachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
DocumentationProvider
Cli OptionDescriptionProperty NamePreferred Annotation LibrarySupported Annotation Libraries
noneDo not publish an OpenAPI specification.withoutDocumentationProvidernonenone, swagger1, swagger2, microprofile
sourcePublish the original input OpenAPI specification.sourceDocumentationProvidernonenone, swagger1, swagger2, microprofile
swagger1Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using Swagger-Core 1.x.swagger1DocumentationProviderswagger1swagger1
swagger2Generate an OpenAPI 3 specification using Swagger-Core 2.x.swagger2DocumentationProviderswagger2swagger2
springfoxGenerate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x.springFoxDocumentationProviderswagger1swagger1
springdocGenerate an OpenAPI 3 specification using SpringDoc.springDocDocumentationProviderswagger2swagger2
AnnotationLibrary
Cli OptionDescriptionProperty Name
noneDo not annotate Model and Api with complementary annotations.withoutAnnotationLibrary
swagger1Annotate Model and Api using the Swagger Annotations 1.x library.swagger1AnnotationLibrary
swagger2Annotate Model and Api using the Swagger Annotations 2.x library.swagger2AnnotationLibrary
microprofileAnnotate Model and Api using the Microprofile annotations.microprofileAnnotationLibrary
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
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.

@cachescrubber
cachescrubberforce-pushed
the
feature/documentation_provider_pr
branch
from
0320e69 to
4aaec1dCompareJanuary 9, 2022 09:15
welshm
welshm
reviewed
Jan 10, 2022
View reviewed changes
Comment thread.../openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java
Outdated

Comment thread...pi-generator/src/main/resources/JavaSpring/libraries/spring-boot/openapi2SpringBoot.mustache
 .allowedHeaders("Content-Type");
 }*/
{{^useSpringfox}}
{{^springFoxDocumentationProvider}}
@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the right check? Or is the resource handler needed for specific non-Springfox providers?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just replaced the template variable name - not the logic
@welshmwelshmJan 11, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm... I suspect this will cause issues with some configurations but we can find out later
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java

Comment on lines

+62
 to 
+73

 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),

@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the plan to add support for these providers before submitting this PR?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java
Outdated

@wing328wing328
added this to the 5.4.0 milestone
Jan 16, 2022
@cachescrubber
Merge branch 'master' into feature/documentation_provider_pr
ace2182
# 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
Update spring sample configuration to use the new property
fa103a5
@cachescrubber
Update samples after merge
508665b
@cachescrubber
fix atBean import
cb2e80c
@cachescrubber
Generate all samples
b998d34
@cachescrubber
Add ParameterObject to test
f1e6108
@cachescrubber
cachescrubber
commented
Jan 17, 2022

Copy link


Copy Markdown

ContributorAuthor
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).
@wing328
wing328
commented
Jan 19, 2022

Copy link


Copy Markdown

Member
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
cachescrubber
commented
Jan 19, 2022

Copy link


Copy Markdown

ContributorAuthor
@wing328 I run export_docs_generators.sh and pushed the changes.
@cachescrubbercachescrubber
mentioned this pull request
Jan 21, 2022

Open

6 tasks
@wing328
wing328
merged commit e1c5b22
into
OpenAPITools:masterJan 22, 2022
@wing328
wing328
commented
Jan 22, 2022•

edited

Loading

Copy link


Copy Markdown

Member
@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
@cachescrubber
cachescrubber
deleted the

feature/documentation_provider_pr

branch
January 22, 2022 10:44
@cdprete
cdprete
commented
Jan 30, 2022•

edited

Loading

Copy link


Copy Markdown

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.

This was referenced Jan 30, 2022
 Merged

 Merged

@sjoblomjsjoblomj
mentioned this pull request
Apr 20, 2022
 Merged

4 tasks
@cgual206cgual206
mentioned this pull request
Aug 5, 2025
 Merged

6 tasks
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@wing328wing328wing328 left review comments
@jimschubertjimschubertAwaiting requested review from jimschubert

+1 more reviewer

@welshmwelshmwelshm left review comments
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

Enhancement: New generatorServer: Spring

Projects


None yet


Milestone

5.4.0

Development

Successfully merging this pull request may close these issues.

4 participants

@cachescrubber@welshm@wing328@cdprete

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
[JAVA] new Feature interface: Documentation Provider and Annotation Library - #11258
Merged
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Jan 22, 2022
Merged
[JAVA] new Feature interface: Documentation Provider and Annotation Library#11258
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Conversation
@cachescrubber
@cachescrubbercachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

Contributor
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.
@cachescrubbercachescrubber
mentioned this pull request
Jan 8, 2022
 Closed

5 tasks
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
@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)
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
Docs and samples not updated yet - I'll wait for potential feedback and feasibility check.
@welshm
welshm
commented
Jan 8, 2022

Copy link


Copy Markdown

Contributor
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
cachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
DocumentationProvider
Cli OptionDescriptionProperty NamePreferred Annotation LibrarySupported Annotation Libraries
noneDo not publish an OpenAPI specification.withoutDocumentationProvidernonenone, swagger1, swagger2, microprofile
sourcePublish the original input OpenAPI specification.sourceDocumentationProvidernonenone, swagger1, swagger2, microprofile
swagger1Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using Swagger-Core 1.x.swagger1DocumentationProviderswagger1swagger1
swagger2Generate an OpenAPI 3 specification using Swagger-Core 2.x.swagger2DocumentationProviderswagger2swagger2
springfoxGenerate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x.springFoxDocumentationProviderswagger1swagger1
springdocGenerate an OpenAPI 3 specification using SpringDoc.springDocDocumentationProviderswagger2swagger2
AnnotationLibrary
Cli OptionDescriptionProperty Name
noneDo not annotate Model and Api with complementary annotations.withoutAnnotationLibrary
swagger1Annotate Model and Api using the Swagger Annotations 1.x library.swagger1AnnotationLibrary
swagger2Annotate Model and Api using the Swagger Annotations 2.x library.swagger2AnnotationLibrary
microprofileAnnotate Model and Api using the Microprofile annotations.microprofileAnnotationLibrary
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
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.

@cachescrubber
cachescrubberforce-pushed
the
feature/documentation_provider_pr
branch
from
0320e69 to
4aaec1dCompareJanuary 9, 2022 09:15
welshm
welshm
reviewed
Jan 10, 2022
View reviewed changes
Comment thread.../openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java
Outdated

Comment thread...pi-generator/src/main/resources/JavaSpring/libraries/spring-boot/openapi2SpringBoot.mustache
 .allowedHeaders("Content-Type");
 }*/
{{^useSpringfox}}
{{^springFoxDocumentationProvider}}
@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the right check? Or is the resource handler needed for specific non-Springfox providers?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just replaced the template variable name - not the logic
@welshmwelshmJan 11, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm... I suspect this will cause issues with some configurations but we can find out later
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java

Comment on lines

+62
 to 
+73

 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),

@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the plan to add support for these providers before submitting this PR?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java
Outdated

@wing328wing328
added this to the 5.4.0 milestone
Jan 16, 2022
@cachescrubber
Merge branch 'master' into feature/documentation_provider_pr
ace2182
# 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
Update spring sample configuration to use the new property
fa103a5
@cachescrubber
Update samples after merge
508665b
@cachescrubber
fix atBean import
cb2e80c
@cachescrubber
Generate all samples
b998d34
@cachescrubber
Add ParameterObject to test
f1e6108
@cachescrubber
cachescrubber
commented
Jan 17, 2022

Copy link


Copy Markdown

ContributorAuthor
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).
@wing328
wing328
commented
Jan 19, 2022

Copy link


Copy Markdown

Member
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
cachescrubber
commented
Jan 19, 2022

Copy link


Copy Markdown

ContributorAuthor
@wing328 I run export_docs_generators.sh and pushed the changes.
@cachescrubbercachescrubber
mentioned this pull request
Jan 21, 2022

Open

6 tasks
@wing328
wing328
merged commit e1c5b22
into
OpenAPITools:masterJan 22, 2022
@wing328
wing328
commented
Jan 22, 2022•

edited

Loading

Copy link


Copy Markdown

Member
@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
@cachescrubber
cachescrubber
deleted the

feature/documentation_provider_pr

branch
January 22, 2022 10:44
@cdprete
cdprete
commented
Jan 30, 2022•

edited

Loading

Copy link


Copy Markdown

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.

This was referenced Jan 30, 2022
 Merged

 Merged

@sjoblomjsjoblomj
mentioned this pull request
Apr 20, 2022
 Merged

4 tasks
@cgual206cgual206
mentioned this pull request
Aug 5, 2025
 Merged

6 tasks
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@wing328wing328wing328 left review comments
@jimschubertjimschubertAwaiting requested review from jimschubert

+1 more reviewer

@welshmwelshmwelshm left review comments
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

Enhancement: New generatorServer: Spring

Projects


None yet


Milestone

5.4.0

Development

Successfully merging this pull request may close these issues.

4 participants

@cachescrubber@welshm@wing328@cdprete

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
[JAVA] new Feature interface: Documentation Provider and Annotation Library - #11258
Merged
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Jan 22, 2022
Merged
[JAVA] new Feature interface: Documentation Provider and Annotation Library#11258
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Conversation
@cachescrubber
@cachescrubbercachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

Contributor
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.
@cachescrubbercachescrubber
mentioned this pull request
Jan 8, 2022
 Closed

5 tasks
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
@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)
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
Docs and samples not updated yet - I'll wait for potential feedback and feasibility check.
@welshm
welshm
commented
Jan 8, 2022

Copy link


Copy Markdown

Contributor
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
cachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
DocumentationProvider
Cli OptionDescriptionProperty NamePreferred Annotation LibrarySupported Annotation Libraries
noneDo not publish an OpenAPI specification.withoutDocumentationProvidernonenone, swagger1, swagger2, microprofile
sourcePublish the original input OpenAPI specification.sourceDocumentationProvidernonenone, swagger1, swagger2, microprofile
swagger1Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using Swagger-Core 1.x.swagger1DocumentationProviderswagger1swagger1
swagger2Generate an OpenAPI 3 specification using Swagger-Core 2.x.swagger2DocumentationProviderswagger2swagger2
springfoxGenerate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x.springFoxDocumentationProviderswagger1swagger1
springdocGenerate an OpenAPI 3 specification using SpringDoc.springDocDocumentationProviderswagger2swagger2
AnnotationLibrary
Cli OptionDescriptionProperty Name
noneDo not annotate Model and Api with complementary annotations.withoutAnnotationLibrary
swagger1Annotate Model and Api using the Swagger Annotations 1.x library.swagger1AnnotationLibrary
swagger2Annotate Model and Api using the Swagger Annotations 2.x library.swagger2AnnotationLibrary
microprofileAnnotate Model and Api using the Microprofile annotations.microprofileAnnotationLibrary
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
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.

@cachescrubber
cachescrubberforce-pushed
the
feature/documentation_provider_pr
branch
from
0320e69 to
4aaec1dCompareJanuary 9, 2022 09:15
welshm
welshm
reviewed
Jan 10, 2022
View reviewed changes
Comment thread.../openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java
Outdated

Comment thread...pi-generator/src/main/resources/JavaSpring/libraries/spring-boot/openapi2SpringBoot.mustache
 .allowedHeaders("Content-Type");
 }*/
{{^useSpringfox}}
{{^springFoxDocumentationProvider}}
@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the right check? Or is the resource handler needed for specific non-Springfox providers?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just replaced the template variable name - not the logic
@welshmwelshmJan 11, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm... I suspect this will cause issues with some configurations but we can find out later
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java

Comment on lines

+62
 to 
+73

 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),

@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the plan to add support for these providers before submitting this PR?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java
Outdated

@wing328wing328
added this to the 5.4.0 milestone
Jan 16, 2022
@cachescrubber
Merge branch 'master' into feature/documentation_provider_pr
ace2182
# 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
Update spring sample configuration to use the new property
fa103a5
@cachescrubber
Update samples after merge
508665b
@cachescrubber
fix atBean import
cb2e80c
@cachescrubber
Generate all samples
b998d34
@cachescrubber
Add ParameterObject to test
f1e6108
@cachescrubber
cachescrubber
commented
Jan 17, 2022

Copy link


Copy Markdown

ContributorAuthor
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).
@wing328
wing328
commented
Jan 19, 2022

Copy link


Copy Markdown

Member
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
cachescrubber
commented
Jan 19, 2022

Copy link


Copy Markdown

ContributorAuthor
@wing328 I run export_docs_generators.sh and pushed the changes.
@cachescrubbercachescrubber
mentioned this pull request
Jan 21, 2022

Open

6 tasks
@wing328
wing328
merged commit e1c5b22
into
OpenAPITools:masterJan 22, 2022
@wing328
wing328
commented
Jan 22, 2022•

edited

Loading

Copy link


Copy Markdown

Member
@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
@cachescrubber
cachescrubber
deleted the

feature/documentation_provider_pr

branch
January 22, 2022 10:44
@cdprete
cdprete
commented
Jan 30, 2022•

edited

Loading

Copy link


Copy Markdown

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.

This was referenced Jan 30, 2022
 Merged

 Merged

@sjoblomjsjoblomj
mentioned this pull request
Apr 20, 2022
 Merged

4 tasks
@cgual206cgual206
mentioned this pull request
Aug 5, 2025
 Merged

6 tasks
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@wing328wing328wing328 left review comments
@jimschubertjimschubertAwaiting requested review from jimschubert

+1 more reviewer

@welshmwelshmwelshm left review comments
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

Enhancement: New generatorServer: Spring

Projects


None yet


Milestone

5.4.0

Development

Successfully merging this pull request may close these issues.

4 participants

@cachescrubber@welshm@wing328@cdprete

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
[JAVA] new Feature interface: Documentation Provider and Annotation Library - #11258
Merged
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Jan 22, 2022
Merged
[JAVA] new Feature interface: Documentation Provider and Annotation Library#11258
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Conversation
@cachescrubber
@cachescrubbercachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

Contributor
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.
@cachescrubbercachescrubber
mentioned this pull request
Jan 8, 2022
 Closed

5 tasks
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
@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)
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
Docs and samples not updated yet - I'll wait for potential feedback and feasibility check.
@welshm
welshm
commented
Jan 8, 2022

Copy link


Copy Markdown

Contributor
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
cachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
DocumentationProvider
Cli OptionDescriptionProperty NamePreferred Annotation LibrarySupported Annotation Libraries
noneDo not publish an OpenAPI specification.withoutDocumentationProvidernonenone, swagger1, swagger2, microprofile
sourcePublish the original input OpenAPI specification.sourceDocumentationProvidernonenone, swagger1, swagger2, microprofile
swagger1Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using Swagger-Core 1.x.swagger1DocumentationProviderswagger1swagger1
swagger2Generate an OpenAPI 3 specification using Swagger-Core 2.x.swagger2DocumentationProviderswagger2swagger2
springfoxGenerate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x.springFoxDocumentationProviderswagger1swagger1
springdocGenerate an OpenAPI 3 specification using SpringDoc.springDocDocumentationProviderswagger2swagger2
AnnotationLibrary
Cli OptionDescriptionProperty Name
noneDo not annotate Model and Api with complementary annotations.withoutAnnotationLibrary
swagger1Annotate Model and Api using the Swagger Annotations 1.x library.swagger1AnnotationLibrary
swagger2Annotate Model and Api using the Swagger Annotations 2.x library.swagger2AnnotationLibrary
microprofileAnnotate Model and Api using the Microprofile annotations.microprofileAnnotationLibrary
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
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.

@cachescrubber
cachescrubberforce-pushed
the
feature/documentation_provider_pr
branch
from
0320e69 to
4aaec1dCompareJanuary 9, 2022 09:15
welshm
welshm
reviewed
Jan 10, 2022
View reviewed changes
Comment thread.../openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java
Outdated

Comment thread...pi-generator/src/main/resources/JavaSpring/libraries/spring-boot/openapi2SpringBoot.mustache
 .allowedHeaders("Content-Type");
 }*/
{{^useSpringfox}}
{{^springFoxDocumentationProvider}}
@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the right check? Or is the resource handler needed for specific non-Springfox providers?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just replaced the template variable name - not the logic
@welshmwelshmJan 11, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm... I suspect this will cause issues with some configurations but we can find out later
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java

Comment on lines

+62
 to 
+73

 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),

@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the plan to add support for these providers before submitting this PR?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java
Outdated

@wing328wing328
added this to the 5.4.0 milestone
Jan 16, 2022
@cachescrubber
Merge branch 'master' into feature/documentation_provider_pr
ace2182
# 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
Update spring sample configuration to use the new property
fa103a5
@cachescrubber
Update samples after merge
508665b
@cachescrubber
fix atBean import
cb2e80c
@cachescrubber
Generate all samples
b998d34
@cachescrubber
Add ParameterObject to test
f1e6108
@cachescrubber
cachescrubber
commented
Jan 17, 2022

Copy link


Copy Markdown

ContributorAuthor
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).
@wing328
wing328
commented
Jan 19, 2022

Copy link


Copy Markdown

Member
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
cachescrubber
commented
Jan 19, 2022

Copy link


Copy Markdown

ContributorAuthor
@wing328 I run export_docs_generators.sh and pushed the changes.
@cachescrubbercachescrubber
mentioned this pull request
Jan 21, 2022

Open

6 tasks
@wing328
wing328
merged commit e1c5b22
into
OpenAPITools:masterJan 22, 2022
@wing328
wing328
commented
Jan 22, 2022•

edited

Loading

Copy link


Copy Markdown

Member
@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
@cachescrubber
cachescrubber
deleted the

feature/documentation_provider_pr

branch
January 22, 2022 10:44
@cdprete
cdprete
commented
Jan 30, 2022•

edited

Loading

Copy link


Copy Markdown

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.

This was referenced Jan 30, 2022
 Merged

 Merged

@sjoblomjsjoblomj
mentioned this pull request
Apr 20, 2022
 Merged

4 tasks
@cgual206cgual206
mentioned this pull request
Aug 5, 2025
 Merged

6 tasks
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@wing328wing328wing328 left review comments
@jimschubertjimschubertAwaiting requested review from jimschubert

+1 more reviewer

@welshmwelshmwelshm left review comments
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

Enhancement: New generatorServer: Spring

Projects


None yet


Milestone

5.4.0

Development

Successfully merging this pull request may close these issues.

4 participants

@cachescrubber@welshm@wing328@cdprete

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
[JAVA] new Feature interface: Documentation Provider and Annotation Library - #11258
Merged
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Jan 22, 2022
Merged
[JAVA] new Feature interface: Documentation Provider and Annotation Library#11258
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Conversation
@cachescrubber
@cachescrubbercachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

Contributor
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.
@cachescrubbercachescrubber
mentioned this pull request
Jan 8, 2022
 Closed

5 tasks
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
@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)
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
Docs and samples not updated yet - I'll wait for potential feedback and feasibility check.
@welshm
welshm
commented
Jan 8, 2022

Copy link


Copy Markdown

Contributor
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
cachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
DocumentationProvider
Cli OptionDescriptionProperty NamePreferred Annotation LibrarySupported Annotation Libraries
noneDo not publish an OpenAPI specification.withoutDocumentationProvidernonenone, swagger1, swagger2, microprofile
sourcePublish the original input OpenAPI specification.sourceDocumentationProvidernonenone, swagger1, swagger2, microprofile
swagger1Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using Swagger-Core 1.x.swagger1DocumentationProviderswagger1swagger1
swagger2Generate an OpenAPI 3 specification using Swagger-Core 2.x.swagger2DocumentationProviderswagger2swagger2
springfoxGenerate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x.springFoxDocumentationProviderswagger1swagger1
springdocGenerate an OpenAPI 3 specification using SpringDoc.springDocDocumentationProviderswagger2swagger2
AnnotationLibrary
Cli OptionDescriptionProperty Name
noneDo not annotate Model and Api with complementary annotations.withoutAnnotationLibrary
swagger1Annotate Model and Api using the Swagger Annotations 1.x library.swagger1AnnotationLibrary
swagger2Annotate Model and Api using the Swagger Annotations 2.x library.swagger2AnnotationLibrary
microprofileAnnotate Model and Api using the Microprofile annotations.microprofileAnnotationLibrary
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
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.

@cachescrubber
cachescrubberforce-pushed
the
feature/documentation_provider_pr
branch
from
0320e69 to
4aaec1dCompareJanuary 9, 2022 09:15
welshm
welshm
reviewed
Jan 10, 2022
View reviewed changes
Comment thread.../openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java
Outdated

Comment thread...pi-generator/src/main/resources/JavaSpring/libraries/spring-boot/openapi2SpringBoot.mustache
 .allowedHeaders("Content-Type");
 }*/
{{^useSpringfox}}
{{^springFoxDocumentationProvider}}
@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the right check? Or is the resource handler needed for specific non-Springfox providers?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just replaced the template variable name - not the logic
@welshmwelshmJan 11, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm... I suspect this will cause issues with some configurations but we can find out later
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java

Comment on lines

+62
 to 
+73

 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),

@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the plan to add support for these providers before submitting this PR?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java
Outdated

@wing328wing328
added this to the 5.4.0 milestone
Jan 16, 2022
@cachescrubber
Merge branch 'master' into feature/documentation_provider_pr
ace2182
# 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
Update spring sample configuration to use the new property
fa103a5
@cachescrubber
Update samples after merge
508665b
@cachescrubber
fix atBean import
cb2e80c
@cachescrubber
Generate all samples
b998d34
@cachescrubber
Add ParameterObject to test
f1e6108
@cachescrubber
cachescrubber
commented
Jan 17, 2022

Copy link


Copy Markdown

ContributorAuthor
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).
@wing328
wing328
commented
Jan 19, 2022

Copy link


Copy Markdown

Member
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
cachescrubber
commented
Jan 19, 2022

Copy link


Copy Markdown

ContributorAuthor
@wing328 I run export_docs_generators.sh and pushed the changes.
@cachescrubbercachescrubber
mentioned this pull request
Jan 21, 2022

Open

6 tasks
@wing328
wing328
merged commit e1c5b22
into
OpenAPITools:masterJan 22, 2022
@wing328
wing328
commented
Jan 22, 2022•

edited

Loading

Copy link


Copy Markdown

Member
@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
@cachescrubber
cachescrubber
deleted the

feature/documentation_provider_pr

branch
January 22, 2022 10:44
@cdprete
cdprete
commented
Jan 30, 2022•

edited

Loading

Copy link


Copy Markdown

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.

This was referenced Jan 30, 2022
 Merged

 Merged

@sjoblomjsjoblomj
mentioned this pull request
Apr 20, 2022
 Merged

4 tasks
@cgual206cgual206
mentioned this pull request
Aug 5, 2025
 Merged

6 tasks
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@wing328wing328wing328 left review comments
@jimschubertjimschubertAwaiting requested review from jimschubert

+1 more reviewer

@welshmwelshmwelshm left review comments
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

Enhancement: New generatorServer: Spring

Projects


None yet


Milestone

5.4.0

Development

Successfully merging this pull request may close these issues.

4 participants

@cachescrubber@welshm@wing328@cdprete

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
[JAVA] new Feature interface: Documentation Provider and Annotation Library - #11258
Merged
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Jan 22, 2022
Merged
[JAVA] new Feature interface: Documentation Provider and Annotation Library#11258
wing328 merged 23 commits into
OpenAPITools:masterfrom 
cachescrubber:feature/documentation_provider_pr
Conversation
@cachescrubber
@cachescrubbercachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

Contributor
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.
@cachescrubbercachescrubber
mentioned this pull request
Jan 8, 2022
 Closed

5 tasks
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
@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)
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
Docs and samples not updated yet - I'll wait for potential feedback and feasibility check.
@welshm
welshm
commented
Jan 8, 2022

Copy link


Copy Markdown

Contributor
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
cachescrubber
commented
Jan 8, 2022•

edited

Loading

Copy link


Copy Markdown

ContributorAuthor
DocumentationProvider
Cli OptionDescriptionProperty NamePreferred Annotation LibrarySupported Annotation Libraries
noneDo not publish an OpenAPI specification.withoutDocumentationProvidernonenone, swagger1, swagger2, microprofile
sourcePublish the original input OpenAPI specification.sourceDocumentationProvidernonenone, swagger1, swagger2, microprofile
swagger1Generate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using Swagger-Core 1.x.swagger1DocumentationProviderswagger1swagger1
swagger2Generate an OpenAPI 3 specification using Swagger-Core 2.x.swagger2DocumentationProviderswagger2swagger2
springfoxGenerate a OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x.springFoxDocumentationProviderswagger1swagger1
springdocGenerate an OpenAPI 3 specification using SpringDoc.springDocDocumentationProviderswagger2swagger2
AnnotationLibrary
Cli OptionDescriptionProperty Name
noneDo not annotate Model and Api with complementary annotations.withoutAnnotationLibrary
swagger1Annotate Model and Api using the Swagger Annotations 1.x library.swagger1AnnotationLibrary
swagger2Annotate Model and Api using the Swagger Annotations 2.x library.swagger2AnnotationLibrary
microprofileAnnotate Model and Api using the Microprofile annotations.microprofileAnnotationLibrary
@cachescrubber
cachescrubber
commented
Jan 8, 2022

Copy link


Copy Markdown

ContributorAuthor
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.

@cachescrubber
cachescrubberforce-pushed
the
feature/documentation_provider_pr
branch
from
0320e69 to
4aaec1dCompareJanuary 9, 2022 09:15
welshm
welshm
reviewed
Jan 10, 2022
View reviewed changes
Comment thread.../openapi-generator/src/main/java/org/openapitools/codegen/languages/AbstractJavaCodegen.java
Outdated

Comment thread...pi-generator/src/main/resources/JavaSpring/libraries/spring-boot/openapi2SpringBoot.mustache
 .allowedHeaders("Content-Type");
 }*/
{{^useSpringfox}}
{{^springFoxDocumentationProvider}}
@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the right check? Or is the resource handler needed for specific non-Springfox providers?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just replaced the template variable name - not the logic
@welshmwelshmJan 11, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm... I suspect this will cause issues with some configurations but we can find out later
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java

Comment on lines

+62
 to 
+73

 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),

@welshmwelshmJan 10, 2022

Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the plan to add support for these providers before submitting this PR?
@cachescrubbercachescrubberJan 10, 2022

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Comment thread...src/main/java/org/openapitools/codegen/languages/features/DocumentationProviderFeatures.java
Outdated

@wing328wing328
added this to the 5.4.0 milestone
Jan 16, 2022
@cachescrubber
Merge branch 'master' into feature/documentation_provider_pr
ace2182
# 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
Update spring sample configuration to use the new property
fa103a5
@cachescrubber
Update samples after merge
508665b
@cachescrubber
fix atBean import
cb2e80c
@cachescrubber
Generate all samples
b998d34
@cachescrubber
Add ParameterObject to test
f1e6108
@cachescrubber
cachescrubber
commented
Jan 17, 2022

Copy link


Copy Markdown

ContributorAuthor
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).
@wing328
wing328
commented
Jan 19, 2022

Copy link


Copy Markdown

Member
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
cachescrubber
commented
Jan 19, 2022

Copy link


Copy Markdown

ContributorAuthor
@wing328 I run export_docs_generators.sh and pushed the changes.
@cachescrubbercachescrubber
mentioned this pull request
Jan 21, 2022

Open

6 tasks
@wing328
wing328
merged commit e1c5b22
into
OpenAPITools:masterJan 22, 2022
@wing328
wing328
commented
Jan 22, 2022•

edited

Loading

Copy link


Copy Markdown

Member
@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
@cachescrubber
cachescrubber
deleted the

feature/documentation_provider_pr

branch
January 22, 2022 10:44
@cdprete
cdprete
commented
Jan 30, 2022•

edited

Loading

Copy link


Copy Markdown

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.

This was referenced Jan 30, 2022
 Merged

 Merged

@sjoblomjsjoblomj
mentioned this pull request
Apr 20, 2022
 Merged

4 tasks
@cgual206cgual206
mentioned this pull request
Aug 5, 2025
 Merged

6 tasks
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@wing328wing328wing328 left review comments
@jimschubertjimschubertAwaiting requested review from jimschubert

+1 more reviewer

@welshmwelshmwelshm left review comments
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

Enhancement: New generatorServer: Spring

Projects


None yet


Milestone

5.4.0

Development

Successfully merging this pull request may close these issues.

4 participants

@cachescrubber@welshm@wing328@cdprete