Skip to content

Commit 94f1fb5

Browse files
committed
Support externalDocs configure on SpecPropertiesCustomizer
Fixes #3028
1 parent ca5fdf5 commit 94f1fb5

File tree

11 files changed

+69
-7
lines changed

11 files changed

+69
-7
lines changed

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/customizers/SpecPropertiesCustomizer.java

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,8 @@
3232
import java.util.function.Consumer;
3333
import java.util.function.Supplier;
3434

35-
import io.swagger.v3.oas.models.Components;
36-
import io.swagger.v3.oas.models.OpenAPI;
37-
import io.swagger.v3.oas.models.Operation;
38-
import io.swagger.v3.oas.models.PathItem;
35+
import io.swagger.v3.oas.models.*;
3936
import io.swagger.v3.oas.models.PathItem.HttpMethod;
40-
import io.swagger.v3.oas.models.Paths;
4137
import io.swagger.v3.oas.models.info.Contact;
4238
import io.swagger.v3.oas.models.info.Info;
4339
import io.swagger.v3.oas.models.info.License;
@@ -90,6 +86,7 @@
9086
*
9187
* @author Anton Tkachenko [email protected]
9288
* @author bnasslahsen
89+
* @author Hujin Hong
9390
*/
9491
public class SpecPropertiesCustomizer implements GlobalOpenApiCustomizer {
9592

@@ -148,6 +145,27 @@ private void customizeOpenApi(OpenAPI openApi, OpenAPI openApiProperties) {
148145
if (!CollectionUtils.isEmpty(openApiProperties.getServers())) {
149146
openApi.setServers(new ArrayList<>(openApiProperties.getServers()));
150147
}
148+
149+
ExternalDocumentation externalDocumentationProperties = openApiProperties.getExternalDocs();
150+
if (externalDocumentationProperties != null) {
151+
customizeExternalDocs(openApi, externalDocumentationProperties);
152+
}
153+
}
154+
}
155+
156+
/**
157+
* Customized external docs.
158+
*
159+
* @param openApi the open api
160+
* @param externalDocumentationProperties the external documentation
161+
*/
162+
private void customizeExternalDocs(OpenAPI openApi, ExternalDocumentation externalDocumentationProperties) {
163+
ExternalDocumentation externalDocumentation = openApi.getExternalDocs();
164+
if (externalDocumentation != null) {
165+
resolveString(externalDocumentation::description, externalDocumentationProperties::getDescription);
166+
resolveString(externalDocumentation::url, externalDocumentationProperties::getUrl);
167+
} else {
168+
openApi.externalDocs(externalDocumentationProperties);
151169
}
152170
}
153171

springdoc-openapi-starter-webmvc-api/src/test/resources/application-212.yml

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,10 @@ springdoc:
3636
- hello
3737
summary: Summary of Get operationId 'persons'
3838
description: Description of Get operationId 'persons'
39-
39+
external-docs:
40+
description: External docs description
41+
url: "https://example.com/external-docs"
42+
4043
group-configs:
4144
- group: apiGroupName
4245
open-api:
@@ -52,10 +55,13 @@ springdoc:
5255
name:
5356
description: Description for 'name' property in ApiGroupName
5457
example: Example value for 'name' property in ApiGroupName
55-
58+
5659
paths:
5760
/persons2:
5861
get:
5962
summary: Summary of operationId 'persons' in ApiGroupName
6063
description: Description of operationId 'persons' in ApiGroupName
64+
external-docs:
65+
description: External docs description for ApiGroupName
66+
url: "https://example.com/apiGroupName-external-docs"
6167

springdoc-openapi-starter-webmvc-api/src/test/resources/application-217.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@ springdoc:
2222
type: http
2323
scheme: bearer
2424
bearer-format: JWT
25+
external-docs:
26+
description: Example External Docs demo
27+
url: "https://example.com/external-docs-demo"
2528
- group: user
2629
display-name: User Interfaces
2730
packages-to-scan:
@@ -46,6 +49,9 @@ springdoc:
4649
name:
4750
description: Description for 'name' property
4851
example: Example value for 'name' property
52+
external-docs:
53+
description: Example External Docs user
54+
url: "https://example.com/external-docs-user"
4955
open-api:
5056
servers:
5157
- url: "https://api.example.com"

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app212-grouped.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,5 +127,9 @@
127127
"bearerFormat": "JWT"
128128
}
129129
}
130+
},
131+
"externalDocs": {
132+
"description": "External docs description for ApiGroupName",
133+
"url": "https://example.com/apiGroupName-external-docs"
130134
}
131135
}

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app212.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,5 +125,9 @@
125125
"bearerFormat": "JWT"
126126
}
127127
}
128+
},
129+
"externalDocs": {
130+
"description": "External docs description",
131+
"url": "https://example.com/external-docs"
128132
}
129133
}

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app217-1.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,5 +58,9 @@
5858
"bearerFormat": "JWT"
5959
}
6060
}
61+
},
62+
"externalDocs": {
63+
"description": "Example External Docs demo",
64+
"url": "https://example.com/external-docs-demo"
6165
}
6266
}

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app217-2.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,5 +51,9 @@
5151
"description": "Description for PersonDTO component"
5252
}
5353
}
54+
},
55+
"externalDocs": {
56+
"description": "Example External Docs user",
57+
"url": "https://example.com/external-docs-user"
5458
}
5559
}

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app212-grouped.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,5 +127,9 @@
127127
"bearerFormat": "JWT"
128128
}
129129
}
130+
},
131+
"externalDocs": {
132+
"description": "External docs description for ApiGroupName",
133+
"url": "https://example.com/apiGroupName-external-docs"
130134
}
131135
}

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app212.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,5 +125,9 @@
125125
"bearerFormat": "JWT"
126126
}
127127
}
128+
},
129+
"externalDocs": {
130+
"description": "External docs description",
131+
"url": "https://example.com/external-docs"
128132
}
129133
}

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app217-1.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,5 +58,9 @@
5858
"bearerFormat": "JWT"
5959
}
6060
}
61+
},
62+
"externalDocs": {
63+
"description": "Example External Docs demo",
64+
"url": "https://example.com/external-docs-demo"
6165
}
6266
}

0 commit comments

Comments
 (0)