[java][spring] added springdoc support for service metadata and security (#12346)

* added springdoc config file to codegen

* added mustache template for springdoc config

* changed type to all caps so it can be used in the template

* added security scheme details
caveat: didn't add oauth2 flows

* removed url not supported by codegensecurity

* Fixed default doc provider in help message

* refactored config file generation test
and added springdoc test

* removed default codegen modification
implemented through booleans in template instead

* added new/updated generator files

* fixed escaping of description

* fixed appDescription in template
removed if and fixed escaping

* updated generated files again

* updated to springdoc in generator docs
This commit is contained in:
Nick Dunne 2022-05-17 22:20:54 -05:00 committed by GitHub
parent 35dc6451e4
commit d38cb1b37a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 418 additions and 15 deletions

View File

@ -11,7 +11,7 @@ title: Documentation for the spring Generator
| generator type | SERVER | |
| generator language | Java | |
| generator default templating engine | mustache | |
| helpTxt | Generates a Java SpringBoot Server application using the SpringFox integration. | |
| helpTxt | Generates a Java SpringBoot Server application using the SpringDoc integration. | |
## CONFIG OPTIONS
These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to [configuration docs](https://openapi-generator.tech/docs/configuration) for more details.

View File

@ -228,7 +228,7 @@ public class SpringCodegen extends AbstractJavaCodegen
@Override
public String getHelp() {
return "Generates a Java SpringBoot Server application using the SpringFox integration.";
return "Generates a Java SpringBoot Server application using the SpringDoc integration.";
}
@Override
@ -471,10 +471,16 @@ public class SpringCodegen extends AbstractJavaCodegen
"HomeController.java"));
supportingFiles.add(new SupportingFile("openapi.mustache",
("src/main/resources").replace("/", java.io.File.separator), "openapi.yaml"));
if (DocumentationProvider.SPRINGFOX.equals(getDocumentationProvider()) && !reactive && !apiFirst) {
supportingFiles.add(new SupportingFile("openapiDocumentationConfig.mustache",
(sourceFolder + File.separator + configPackage).replace(".", java.io.File.separator),
"SpringFoxConfiguration.java"));
if (!reactive && !apiFirst){
if (DocumentationProvider.SPRINGDOC.equals(getDocumentationProvider())){
supportingFiles.add(new SupportingFile("springdocDocumentationConfig.mustache",
(sourceFolder + File.separator + configPackage).replace(".", java.io.File.separator),
"SpringDocConfiguration.java"));
} else if (DocumentationProvider.SPRINGFOX.equals(getDocumentationProvider())) {
supportingFiles.add(new SupportingFile("openapiDocumentationConfig.mustache",
(sourceFolder + File.separator + configPackage).replace(".", java.io.File.separator),
"SpringFoxConfiguration.java"));
}
}
}
}

View File

@ -0,0 +1,54 @@
package {{configPackage}};
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityScheme;
@Configuration
public class SpringDocConfiguration {
@Bean
OpenAPI apiInfo() {
return new OpenAPI()
.info(
new Info(){{#appName}}
.title("{{appName}}"){{/appName}}
.description("{{{appDescription}}}"){{#termsOfService}}
.termsOfService("{{termsOfService}}"){{/termsOfService}}{{#openAPI}}{{#info}}{{#contact}}
.contact(
new Contact(){{#infoName}}
.name("{{infoName}}"){{/infoName}}{{#infoUrl}}
.url("{{infoUrl}}"){{/infoUrl}}{{#infoEmail}}
.email("{{infoEmail}}"){{/infoEmail}}
){{/contact}}{{#license}}
.license(
new License()
{{#licenseInfo}}.name("{{licenseInfo}}")
{{/licenseInfo}}{{#licenseUrl}}.url("{{licenseUrl}}")
{{/licenseUrl}}
){{/license}}{{/info}}{{/openAPI}}
.version("{{appVersion}}")
){{#hasAuthMethods}}
.components(
new Components(){{#authMethods}}
.addSecuritySchemes("{{name}}", new SecurityScheme(){{#isBasic}}
.type(SecurityScheme.Type.HTTP)
.scheme("{{scheme}}"){{#bearerFormat}}
.bearerFormat("{{bearerFormat}}"){{/bearerFormat}}{{/isBasic}}{{#isApiKey}}
.type(SecurityScheme.Type.APIKEY){{#isKeyInHeader}}
.in(SecurityScheme.In.HEADER){{/isKeyInHeader}}{{#isKeyInQuery}}
.in(SecurityScheme.In.QUERY){{/isKeyInQuery}}{{#isKeyInCookie}}
.in(SecurityScheme.In.COOKIE){{/isKeyInCookie}}
.name("{{keyParamName}}"){{/isApiKey}}{{#isOAuth}}
.type(SecurityScheme.Type.OAUTH2){{/isOAuth}}
){{/authMethods}}
){{/hasAuthMethods}}
;
}
}

View File

@ -848,20 +848,35 @@ public class SpringCodegenTest {
}
/**define the destinationFilename*/
private final static String DESTINATIONFILE = "SpringFoxConfiguration.java";
/**define the templateFile*/
private final static String TEMPLATEFILE = "openapiDocumentationConfig.mustache";
/**Define documentation providers to test */
private final static String SPRINGFOX = "springfox";
private final static String SPRINGFOX_DESTINATIONFILE = "SpringFoxConfiguration.java";
private final static String SPRINGFOX_TEMPLATEFILE = "openapiDocumentationConfig.mustache";
private final static String SPRINGDOC = "springdoc";
private final static String SPRINGDOC_DESTINATIONFILE = "SpringDocConfiguration.java";
private final static String SPRINGDOC_TEMPLATEFILE = "springdocDocumentationConfig.mustache";
/**
* test whether OpenAPIDocumentationConfig.java is generated
* fix issue #10287
*/
@Test
public void testConfigFileGeneration() {
public void testConfigFileGeneration_springfox() {
testConfigFileCommon(SPRINGFOX, SPRINGFOX_DESTINATIONFILE, SPRINGFOX_TEMPLATEFILE);
}
/**
* test whether SpringDocDocumentationConfig.java is generated
* fix issue #12220
*/
@Test
public void testConfigFileGeneration_springdoc() {
testConfigFileCommon(SPRINGDOC, SPRINGDOC_DESTINATIONFILE, SPRINGDOC_TEMPLATEFILE);
}
private void testConfigFileCommon(String documentationProvider, String destinationFile, String templateFileName){
final SpringCodegen codegen = new SpringCodegen();
codegen.additionalProperties().put(DOCUMENTATION_PROVIDER, "springfox");
codegen.additionalProperties().put(DOCUMENTATION_PROVIDER, documentationProvider);
codegen.additionalProperties().put(SpringCodegen.INTERFACE_ONLY, false);
codegen.additionalProperties().put(SpringCodegen.SPRING_CLOUD_LIBRARY, "spring-cloud");
codegen.additionalProperties().put(SpringCodegen.REACTIVE, false);
@ -877,13 +892,13 @@ public class SpringCodegenTest {
tmpFile = s.getTemplateFile();
desFile = s.getDestinationFilename();
if (TEMPLATEFILE.equals(tmpFile)) {
if (templateFileName.equals(tmpFile)) {
flag = true;
assertEquals(desFile, DESTINATIONFILE);
assertEquals(desFile, destinationFile);
}
}
if (!flag) {
fail("OpenAPIDocumentationConfig.java not generated");
fail(templateFileName + " not generated");
}
}

View File

@ -8,6 +8,7 @@ src/main/java/org/openapitools/api/BarApiController.java
src/main/java/org/openapitools/api/FooApi.java
src/main/java/org/openapitools/api/FooApiController.java
src/main/java/org/openapitools/configuration/HomeController.java
src/main/java/org/openapitools/configuration/SpringDocConfiguration.java
src/main/java/org/openapitools/model/Addressable.java
src/main/java/org/openapitools/model/Bar.java
src/main/java/org/openapitools/model/BarCreate.java

View File

@ -0,0 +1,27 @@
package org.openapitools.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityScheme;
@Configuration
public class SpringDocConfiguration {
@Bean
OpenAPI apiInfo() {
return new OpenAPI()
.info(
new Info()
.title("ByRefOrValue")
.description("This tests for a oneOf interface representation ")
.version("0.0.1")
)
;
}
}

View File

@ -10,6 +10,7 @@ src/main/java/org/openapitools/api/StoreApiController.java
src/main/java/org/openapitools/api/UserApi.java
src/main/java/org/openapitools/api/UserApiController.java
src/main/java/org/openapitools/configuration/HomeController.java
src/main/java/org/openapitools/configuration/SpringDocConfiguration.java
src/main/java/org/openapitools/model/Category.java
src/main/java/org/openapitools/model/ModelApiResponse.java
src/main/java/org/openapitools/model/Order.java

View File

@ -0,0 +1,43 @@
package org.openapitools.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityScheme;
@Configuration
public class SpringDocConfiguration {
@Bean
OpenAPI apiInfo() {
return new OpenAPI()
.info(
new Info()
.title("OpenAPI Petstore")
.description("This is a sample server Petstore server. For this sample, you can use the api key `special-key` to test the authorization filters.")
.license(
new License()
.name("Apache-2.0")
.url("https://www.apache.org/licenses/LICENSE-2.0.html")
)
.version("1.0.0")
)
.components(
new Components()
.addSecuritySchemes("api_key", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name("api_key")
)
.addSecuritySchemes("petstore_auth", new SecurityScheme()
.type(SecurityScheme.Type.OAUTH2)
)
)
;
}
}

View File

@ -16,6 +16,7 @@ src/main/java/org/openapitools/api/StoreApiController.java
src/main/java/org/openapitools/api/UserApi.java
src/main/java/org/openapitools/api/UserApiController.java
src/main/java/org/openapitools/configuration/HomeController.java
src/main/java/org/openapitools/configuration/SpringDocConfiguration.java
src/main/java/org/openapitools/model/AdditionalPropertiesAnyType.java
src/main/java/org/openapitools/model/AdditionalPropertiesArray.java
src/main/java/org/openapitools/model/AdditionalPropertiesBoolean.java

View File

@ -0,0 +1,52 @@
package org.openapitools.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityScheme;
@Configuration
public class SpringDocConfiguration {
@Bean
OpenAPI apiInfo() {
return new OpenAPI()
.info(
new Info()
.title("OpenAPI Petstore")
.description("This spec is mainly for testing Petstore server and contains fake endpoints, models. Please do not use this for any other purpose. Special characters: \" \\")
.license(
new License()
.name("Apache-2.0")
.url("https://www.apache.org/licenses/LICENSE-2.0.html")
)
.version("1.0.0")
)
.components(
new Components()
.addSecuritySchemes("api_key", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name("api_key")
)
.addSecuritySchemes("api_key_query", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.QUERY)
.name("api_key_query")
)
.addSecuritySchemes("http_basic_test", new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("basic")
)
.addSecuritySchemes("petstore_auth", new SecurityScheme()
.type(SecurityScheme.Type.OAUTH2)
)
)
;
}
}

View File

@ -22,6 +22,7 @@ src/main/java/org/openapitools/api/UserApi.java
src/main/java/org/openapitools/api/UserApiController.java
src/main/java/org/openapitools/api/UserApiDelegate.java
src/main/java/org/openapitools/configuration/HomeController.java
src/main/java/org/openapitools/configuration/SpringDocConfiguration.java
src/main/java/org/openapitools/model/AdditionalPropertiesAnyType.java
src/main/java/org/openapitools/model/AdditionalPropertiesArray.java
src/main/java/org/openapitools/model/AdditionalPropertiesBoolean.java

View File

@ -0,0 +1,52 @@
package org.openapitools.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityScheme;
@Configuration
public class SpringDocConfiguration {
@Bean
OpenAPI apiInfo() {
return new OpenAPI()
.info(
new Info()
.title("OpenAPI Petstore")
.description("This spec is mainly for testing Petstore server and contains fake endpoints, models. Please do not use this for any other purpose. Special characters: \" \\")
.license(
new License()
.name("Apache-2.0")
.url("https://www.apache.org/licenses/LICENSE-2.0.html")
)
.version("1.0.0")
)
.components(
new Components()
.addSecuritySchemes("api_key", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name("api_key")
)
.addSecuritySchemes("api_key_query", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.QUERY)
.name("api_key_query")
)
.addSecuritySchemes("http_basic_test", new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("basic")
)
.addSecuritySchemes("petstore_auth", new SecurityScheme()
.type(SecurityScheme.Type.OAUTH2)
)
)
;
}
}

View File

@ -16,6 +16,7 @@ src/main/java/org/openapitools/api/StoreApiController.java
src/main/java/org/openapitools/api/UserApi.java
src/main/java/org/openapitools/api/UserApiController.java
src/main/java/org/openapitools/configuration/HomeController.java
src/main/java/org/openapitools/configuration/SpringDocConfiguration.java
src/main/java/org/openapitools/model/AdditionalPropertiesAnyType.java
src/main/java/org/openapitools/model/AdditionalPropertiesArray.java
src/main/java/org/openapitools/model/AdditionalPropertiesBoolean.java

View File

@ -0,0 +1,52 @@
package org.openapitools.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityScheme;
@Configuration
public class SpringDocConfiguration {
@Bean
OpenAPI apiInfo() {
return new OpenAPI()
.info(
new Info()
.title("OpenAPI Petstore")
.description("This spec is mainly for testing Petstore server and contains fake endpoints, models. Please do not use this for any other purpose. Special characters: \" \\")
.license(
new License()
.name("Apache-2.0")
.url("https://www.apache.org/licenses/LICENSE-2.0.html")
)
.version("1.0.0")
)
.components(
new Components()
.addSecuritySchemes("api_key", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name("api_key")
)
.addSecuritySchemes("api_key_query", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.QUERY)
.name("api_key_query")
)
.addSecuritySchemes("http_basic_test", new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("basic")
)
.addSecuritySchemes("petstore_auth", new SecurityScheme()
.type(SecurityScheme.Type.OAUTH2)
)
)
;
}
}

View File

@ -16,6 +16,7 @@ src/main/java/org/openapitools/api/StoreApiController.java
src/main/java/org/openapitools/api/UserApi.java
src/main/java/org/openapitools/api/UserApiController.java
src/main/java/org/openapitools/configuration/HomeController.java
src/main/java/org/openapitools/configuration/SpringDocConfiguration.java
src/main/java/org/openapitools/model/AdditionalPropertiesAnyType.java
src/main/java/org/openapitools/model/AdditionalPropertiesArray.java
src/main/java/org/openapitools/model/AdditionalPropertiesBoolean.java

View File

@ -0,0 +1,52 @@
package org.openapitools.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityScheme;
@Configuration
public class SpringDocConfiguration {
@Bean
OpenAPI apiInfo() {
return new OpenAPI()
.info(
new Info()
.title("OpenAPI Petstore")
.description("This spec is mainly for testing Petstore server and contains fake endpoints, models. Please do not use this for any other purpose. Special characters: \" \\")
.license(
new License()
.name("Apache-2.0")
.url("https://www.apache.org/licenses/LICENSE-2.0.html")
)
.version("1.0.0")
)
.components(
new Components()
.addSecuritySchemes("api_key", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name("api_key")
)
.addSecuritySchemes("api_key_query", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.QUERY)
.name("api_key_query")
)
.addSecuritySchemes("http_basic_test", new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("basic")
)
.addSecuritySchemes("petstore_auth", new SecurityScheme()
.type(SecurityScheme.Type.OAUTH2)
)
)
;
}
}

View File

@ -10,6 +10,7 @@ src/main/java/org/openapitools/api/StoreApiController.java
src/main/java/org/openapitools/api/UserApi.java
src/main/java/org/openapitools/api/UserApiController.java
src/main/java/org/openapitools/configuration/HomeController.java
src/main/java/org/openapitools/configuration/SpringDocConfiguration.java
src/main/java/org/openapitools/model/Category.java
src/main/java/org/openapitools/model/ModelApiResponse.java
src/main/java/org/openapitools/model/Order.java

View File

@ -0,0 +1,43 @@
package org.openapitools.configuration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityScheme;
@Configuration
public class SpringDocConfiguration {
@Bean
OpenAPI apiInfo() {
return new OpenAPI()
.info(
new Info()
.title("OpenAPI Petstore")
.description("This is a sample server Petstore server. For this sample, you can use the api key `special-key` to test the authorization filters.")
.license(
new License()
.name("Apache-2.0")
.url("https://www.apache.org/licenses/LICENSE-2.0.html")
)
.version("1.0.0")
)
.components(
new Components()
.addSecuritySchemes("api_key", new SecurityScheme()
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.name("api_key")
)
.addSecuritySchemes("petstore_auth", new SecurityScheme()
.type(SecurityScheme.Type.OAUTH2)
)
)
;
}
}