diff --git a/springdoc-openapi-starter-common/src/main/java/org/springdoc/core/customizers/SpecPropertiesCustomizer.java b/springdoc-openapi-starter-common/src/main/java/org/springdoc/core/customizers/SpecPropertiesCustomizer.java index 130701065..f79612e42 100644 --- a/springdoc-openapi-starter-common/src/main/java/org/springdoc/core/customizers/SpecPropertiesCustomizer.java +++ b/springdoc-openapi-starter-common/src/main/java/org/springdoc/core/customizers/SpecPropertiesCustomizer.java @@ -33,6 +33,7 @@ import java.util.function.Supplier; import io.swagger.v3.oas.models.Components; +import io.swagger.v3.oas.models.ExternalDocumentation; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.Operation; import io.swagger.v3.oas.models.PathItem; @@ -90,6 +91,7 @@ * * @author Anton Tkachenko tkachenkoas@gmail.com * @author bnasslahsen + * @author Huijin Hong */ public class SpecPropertiesCustomizer implements GlobalOpenApiCustomizer { @@ -148,6 +150,27 @@ private void customizeOpenApi(OpenAPI openApi, OpenAPI openApiProperties) { if (!CollectionUtils.isEmpty(openApiProperties.getServers())) { openApi.setServers(new ArrayList<>(openApiProperties.getServers())); } + + ExternalDocumentation externalDocumentationProperties = openApiProperties.getExternalDocs(); + if (externalDocumentationProperties != null) { + customizeExternalDocs(openApi, externalDocumentationProperties); + } + } + } + + /** + * Customized external docs. + * + * @param openApi the open api + * @param externalDocumentationProperties the external documentation + */ + private void customizeExternalDocs(OpenAPI openApi, ExternalDocumentation externalDocumentationProperties) { + ExternalDocumentation externalDocumentation = openApi.getExternalDocs(); + if (externalDocumentation != null) { + resolveString(externalDocumentation::description, externalDocumentationProperties::getDescription); + resolveString(externalDocumentation::url, externalDocumentationProperties::getUrl); + } else { + openApi.setExternalDocs(externalDocumentationProperties); } } diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/application-212.yml b/springdoc-openapi-starter-webmvc-api/src/test/resources/application-212.yml index ee17f35b6..2ccd53f22 100644 --- a/springdoc-openapi-starter-webmvc-api/src/test/resources/application-212.yml +++ b/springdoc-openapi-starter-webmvc-api/src/test/resources/application-212.yml @@ -36,7 +36,10 @@ springdoc: - hello summary: Summary of Get operationId 'persons' description: Description of Get operationId 'persons' - + external-docs: + description: External docs description + url: "https://example.com/external-docs" + group-configs: - group: apiGroupName open-api: @@ -52,10 +55,13 @@ springdoc: name: description: Description for 'name' property in ApiGroupName example: Example value for 'name' property in ApiGroupName - + paths: /persons2: get: summary: Summary of operationId 'persons' in ApiGroupName description: Description of operationId 'persons' in ApiGroupName + external-docs: + description: External docs description for ApiGroupName + url: "https://example.com/apiGroupName-external-docs" diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/application-217.yml b/springdoc-openapi-starter-webmvc-api/src/test/resources/application-217.yml index b80a5886f..a3f2349af 100644 --- a/springdoc-openapi-starter-webmvc-api/src/test/resources/application-217.yml +++ b/springdoc-openapi-starter-webmvc-api/src/test/resources/application-217.yml @@ -22,6 +22,9 @@ springdoc: type: http scheme: bearer bearer-format: JWT + external-docs: + description: Example External Docs demo + url: "https://example.com/external-docs-demo" - group: user display-name: User Interfaces packages-to-scan: @@ -46,6 +49,9 @@ springdoc: name: description: Description for 'name' property example: Example value for 'name' property + external-docs: + description: Example External Docs user + url: "https://example.com/external-docs-user" open-api: servers: - url: "https://api.example.com" diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app212-grouped.json b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app212-grouped.json index 162933459..c47feecfd 100644 --- a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app212-grouped.json +++ b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app212-grouped.json @@ -127,5 +127,9 @@ "bearerFormat": "JWT" } } + }, + "externalDocs": { + "description": "External docs description for ApiGroupName", + "url": "https://example.com/apiGroupName-external-docs" } } diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app212.json b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app212.json index 4e77bed5b..d3824d3eb 100644 --- a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app212.json +++ b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app212.json @@ -125,5 +125,9 @@ "bearerFormat": "JWT" } } + }, + "externalDocs": { + "description": "External docs description", + "url": "https://example.com/external-docs" } } diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app217-1.json b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app217-1.json index 6f7a36277..edd8b64cb 100644 --- a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app217-1.json +++ b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app217-1.json @@ -58,5 +58,9 @@ "bearerFormat": "JWT" } } + }, + "externalDocs": { + "description": "Example External Docs demo", + "url": "https://example.com/external-docs-demo" } } diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app217-2.json b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app217-2.json index f516b8ae6..e77943fbe 100644 --- a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app217-2.json +++ b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app217-2.json @@ -51,5 +51,9 @@ "description": "Description for PersonDTO component" } } + }, + "externalDocs": { + "description": "Example External Docs user", + "url": "https://example.com/external-docs-user" } } diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app212-grouped.json b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app212-grouped.json index 63dc30361..cf3bd1551 100644 --- a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app212-grouped.json +++ b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app212-grouped.json @@ -127,5 +127,9 @@ "bearerFormat": "JWT" } } + }, + "externalDocs": { + "description": "External docs description for ApiGroupName", + "url": "https://example.com/apiGroupName-external-docs" } } diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app212.json b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app212.json index 5584dc48b..7195d2ce0 100644 --- a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app212.json +++ b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app212.json @@ -125,5 +125,9 @@ "bearerFormat": "JWT" } } + }, + "externalDocs": { + "description": "External docs description", + "url": "https://example.com/external-docs" } } diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app217-1.json b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app217-1.json index 00ee1be2d..8be7e9b4a 100644 --- a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app217-1.json +++ b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app217-1.json @@ -58,5 +58,9 @@ "bearerFormat": "JWT" } } + }, + "externalDocs": { + "description": "Example External Docs demo", + "url": "https://example.com/external-docs-demo" } } diff --git a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app217-2.json b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app217-2.json index b92678d15..3da610fa5 100644 --- a/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app217-2.json +++ b/springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app217-2.json @@ -51,5 +51,9 @@ } } } + }, + "externalDocs": { + "description": "Example External Docs user", + "url": "https://example.com/external-docs-user" } }