Merge pull request #3042 from huisam/feature/spec-properties-external-docs

Support externalDocs configure on SpecPropertiesCustomizer

Author: bnasslahsen

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 [email protected]
  * @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);
 		}
 	}
 

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"
 

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"

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"
   }
 }

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"
   }
 }

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"
   }
 }

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"
   }
 }

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"
   }
 }

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"
   }
 }

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"
   }
 }