Feature/openapi spec generation improvements 2

.tool-versions

@@ -0,0 +1,3 @@
+// .tool-versions configures the asdf version manager https://asdf-vm.com/
+maven 3.8.1
+java openjdk-17

hapi-fhir-base/src/main/java/org/hl7/fhir/instance/model/api/IBaseResource.java

@@ -31,7 +31,7 @@
 
 /**
  * For now, this is a simple marker interface indicating that a class is a resource type.
- * There are two concrete types of implementations of this interrface. The first are
+ * There are two concrete types of implementations of this interface. The first are
  * HL7.org's Resource structures (e.g.
  * <code>org.hl7.fhir.instance.model.Patient</code>) and
  * the second are HAPI's Resource structures, e.g.

hapi-fhir-server-openapi/src/main/java/ca/uhn/fhir/rest/openapi/OpenApiInterceptor.java

@@ -26,10 +26,14 @@
 import ca.uhn.fhir.interceptor.api.Hook;
 import ca.uhn.fhir.interceptor.api.Pointcut;
 import ca.uhn.fhir.rest.api.Constants;
+import ca.uhn.fhir.rest.api.RestOperationTypeEnum;
 import ca.uhn.fhir.rest.server.IServerAddressStrategy;
 import ca.uhn.fhir.rest.server.IServerConformanceProvider;
+import ca.uhn.fhir.rest.server.ResourceBinding;
 import ca.uhn.fhir.rest.server.RestfulServer;
 import ca.uhn.fhir.rest.server.RestfulServerUtils;
+import ca.uhn.fhir.rest.server.method.BaseMethodBinding;
+import ca.uhn.fhir.rest.server.method.ReadMethodBinding;
 import ca.uhn.fhir.rest.server.servlet.ServletRequestDetails;
 import ca.uhn.fhir.util.ClasspathUtil;
 import ca.uhn.fhir.util.ExtensionConstants;
@@ -65,6 +69,8 @@
 import jakarta.servlet.ServletContext;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
+import org.apache.commons.collections4.keyvalue.MultiKey;
+import org.apache.commons.collections4.map.MultiKeyMap;
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.lang3.StringUtils;
 import org.hl7.fhir.convertors.factory.VersionConvertorFactory_30_40;
@@ -110,6 +116,7 @@
 import java.math.BigDecimal;
 import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.LinkedHashMap;
@@ -442,6 +449,31 @@ private String extractPageName(ServletRequestDetails theRequestDetails, String t
 		return page;
 	}
 
+	/**
+	 * When implementing your own HAPI server, you can create a class extending this one and override
+	 * this method if you have something in the operations that you want to customize in the
+	 * generated OpenAPI Spec.
+	 *
+	 * @param openApi - The OpenAPI Spec object that is in the process of being generated.
+	 * @param operation - The Operation that is in the process of being generated.
+	 * @param baseMethodBinding - Object containing metadata about the method that processes this operation.
+	 */
+	protected void customizeOperation(OpenAPI openApi, Operation operation, BaseMethodBinding baseMethodBinding) {
+		// Here just to be overridden by extending classes.
+	}
+
+	/**
+	 * When implementing your own HAPI server, you can create a class extending this one and override
+	 * this method if you have something in the operations that you want to customize in the
+	 * generated OpenAPI Spec.
+	 *
+	 * @param openApi - The OpenAPI Spec object that is in the process of being generated.
+	 * @param requestDetails - Details about the request being processed.
+	 */
+	protected void customizeOpenApi(OpenAPI openApi, ServletRequestDetails requestDetails) {
+		// Here just to be overridden by extending classes.
+	}
+
 	protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 		String page = extractPageName(theRequestDetails, null);
 
@@ -454,6 +486,8 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 			capabilitiesProvider = (IServerConformanceProvider<?>) restfulServer.getServerConformanceProvider();
 		}
 
+		final MultiKeyMap<String, BaseMethodBinding> operationLookup = buildOperationLookup(restfulServer);
+
 		OpenAPI openApi = new OpenAPI();
 
 		openApi.setInfo(new Info());
@@ -474,6 +508,10 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 		Paths paths = new Paths();
 		openApi.setPaths(paths);
 
+		ensureComponentsSchemasPopulated(openApi);
+
+		customizeOpenApi(openApi, theRequestDetails);
+
 		if (page == null || page.equals(PAGE_SYSTEM) || page.equals(PAGE_ALL)) {
 			Tag serverTag = new Tag();
 			serverTag.setName(PAGE_SYSTEM);
@@ -495,7 +533,7 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 				Operation transaction = getPathItem(paths, "/", PathItem.HttpMethod.POST);
 				transaction.addTagsItem(PAGE_SYSTEM);
 				transaction.setSummary("server-transaction: Execute a FHIR Transaction (or FHIR Batch) Bundle");
-				addFhirResourceResponse(ctx, openApi, transaction, null);
+				addFhirResourceResponse(ctx, openApi, transaction, "Bundle");
 				addFhirResourceRequestBody(openApi, transaction, ctx, null);
 			}
 
@@ -505,13 +543,14 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 				systemHistory.addTagsItem(PAGE_SYSTEM);
 				systemHistory.setSummary(
 						"server-history: Fetch the resource change history across all resource types on the server");
-				addFhirResourceResponse(ctx, openApi, systemHistory, null);
+				addFhirResourceResponse(ctx, openApi, systemHistory, "Bundle");
 			}
 
 			// System-level Operations
 			for (CapabilityStatement.CapabilityStatementRestResourceOperationComponent nextOperation :
 					cs.getRestFirstRep().getOperation()) {
 				addFhirOperation(ctx, openApi, theRequestDetails, capabilitiesProvider, paths, null, nextOperation);
+				// TODO: customize operations
 			}
 		}
 
@@ -536,10 +575,15 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 			// Instance Read
 			if (typeRestfulInteractions.contains(CapabilityStatement.TypeRestfulInteraction.READ)) {
 				Operation operation = getPathItem(paths, "/" + resourceType + "/{id}", PathItem.HttpMethod.GET);
+
 				operation.addTagsItem(resourceType);
 				operation.setSummary("read-instance: Read " + resourceType + " instance");
 				addResourceIdParameter(operation);
-				addFhirResourceResponse(ctx, openApi, operation, null);
+
+				addFhirResourceResponse(ctx, openApi, operation, resourceType);
+
+				customizeOperation(
+						openApi, operation, operationLookup.get(resourceType, RestOperationTypeEnum.READ.name()));
 			}
 
 			// Instance VRead
@@ -550,7 +594,10 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 				operation.setSummary("vread-instance: Read " + resourceType + " instance with specific version");
 				addResourceIdParameter(operation);
 				addResourceVersionIdParameter(operation);
-				addFhirResourceResponse(ctx, openApi, operation, null);
+				addFhirResourceResponse(ctx, openApi, operation, resourceType);
+
+				customizeOperation(
+						openApi, operation, operationLookup.get(resourceType, RestOperationTypeEnum.VREAD.name()));
 			}
 
 			// Type Create
@@ -560,6 +607,9 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 				operation.setSummary("create-type: Create a new " + resourceType + " instance");
 				addFhirResourceRequestBody(openApi, operation, ctx, genericExampleSupplier(ctx, resourceType));
 				addFhirResourceResponse(ctx, openApi, operation, null);
+
+				customizeOperation(
+						openApi, operation, operationLookup.get(resourceType, RestOperationTypeEnum.CREATE.name()));
 			}
 
 			// Instance Update
@@ -571,6 +621,9 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 				addResourceIdParameter(operation);
 				addFhirResourceRequestBody(openApi, operation, ctx, genericExampleSupplier(ctx, resourceType));
 				addFhirResourceResponse(ctx, openApi, operation, null);
+
+				customizeOperation(
+						openApi, operation, operationLookup.get(resourceType, RestOperationTypeEnum.UPDATE.name()));
 			}
 
 			// Type history
@@ -579,18 +632,28 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 				operation.addTagsItem(resourceType);
 				operation.setSummary(
 						"type-history: Fetch the resource change history for all resources of type " + resourceType);
-				addFhirResourceResponse(ctx, openApi, operation, null);
+				addFhirResourceResponse(ctx, openApi, operation, "Bundle");
+
+				customizeOperation(
+						openApi,
+						operation,
+						operationLookup.get(resourceType, RestOperationTypeEnum.HISTORY_TYPE.name()));
 			}
 
 			// Instance history
-			if (typeRestfulInteractions.contains(CapabilityStatement.TypeRestfulInteraction.HISTORYTYPE)) {
+			if (typeRestfulInteractions.contains(CapabilityStatement.TypeRestfulInteraction.HISTORYINSTANCE)) {
 				Operation operation =
 						getPathItem(paths, "/" + resourceType + "/{id}/_history", PathItem.HttpMethod.GET);
 				operation.addTagsItem(resourceType);
 				operation.setSummary("instance-history: Fetch the resource change history for all resources of type "
 						+ resourceType);
 				addResourceIdParameter(operation);
-				addFhirResourceResponse(ctx, openApi, operation, null);
+				addFhirResourceResponse(ctx, openApi, operation, "Bundle");
+
+				customizeOperation(
+						openApi,
+						operation,
+						operationLookup.get(resourceType, RestOperationTypeEnum.HISTORY_INSTANCE.name()));
 			}
 
 			// Instance Patch
@@ -601,6 +664,9 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 				addResourceIdParameter(operation);
 				addFhirResourceRequestBody(openApi, operation, FHIR_CONTEXT_CANONICAL, patchExampleSupplier());
 				addFhirResourceResponse(ctx, openApi, operation, null);
+
+				customizeOperation(
+						openApi, operation, operationLookup.get(resourceType, RestOperationTypeEnum.PATCH.name()));
 			}
 
 			// Instance Delete
@@ -610,35 +676,74 @@ protected OpenAPI generateOpenApi(ServletRequestDetails theRequestDetails) {
 				operation.setSummary("instance-delete: Perform a logical delete on a resource instance");
 				addResourceIdParameter(operation);
 				addFhirResourceResponse(ctx, openApi, operation, null);
+
+				customizeOperation(
+						openApi, operation, operationLookup.get(resourceType, RestOperationTypeEnum.DELETE.name()));
 			}
 
 			// Search
 			if (typeRestfulInteractions.contains(CapabilityStatement.TypeRestfulInteraction.SEARCHTYPE)) {
+
+				final BaseMethodBinding baseMethodBinding =
+						operationLookup.get(resourceType, RestOperationTypeEnum.SEARCH_TYPE.name());
+
 				addSearchOperation(
 						openApi,
 						getPathItem(paths, "/" + resourceType, PathItem.HttpMethod.GET),
 						ctx,
 						resourceType,
-						nextResource);
+						nextResource,
+						baseMethodBinding);
 				addSearchOperation(
 						openApi,
 						getPathItem(paths, "/" + resourceType + "/_search", PathItem.HttpMethod.GET),
 						ctx,
 						resourceType,
-						nextResource);
+						nextResource,
+						baseMethodBinding);
 			}
 
 			// Resource-level Operations
 			for (CapabilityStatement.CapabilityStatementRestResourceOperationComponent nextOperation :
 					nextResource.getOperation()) {
 				addFhirOperation(
 						ctx, openApi, theRequestDetails, capabilitiesProvider, paths, resourceType, nextOperation);
+
+				// TODO: customize operations
 			}
 		}
 
 		return openApi;
 	}
 
+	/**
+	 * Iterate through the resource bindings on the server to build a lookup of resource + operation name
+	 * to the method binding that will process that operation.
+	 */
+	private MultiKeyMap<String, BaseMethodBinding> buildOperationLookup(RestfulServer restfulServer) {
+
+		final MultiKeyMap<String, BaseMethodBinding> map = new MultiKeyMap<>();
+		final Collection<ResourceBinding> resourceBindings = restfulServer.getResourceBindings();
+		for (ResourceBinding resourceBinding : resourceBindings) {
+			final String resourceName = resourceBinding.getResourceName();
+
+			for (BaseMethodBinding methodBinding : resourceBinding.getMethodBindings()) {
+				final RestOperationTypeEnum restOperationType = methodBinding.getRestOperationType();
+				final MultiKey<String> key = new MultiKey<>(resourceName, restOperationType.name());
+
+				map.put(key, methodBinding);
+
+				if (RestOperationTypeEnum.VREAD.equals(restOperationType)) {
+					map.put(resourceName, RestOperationTypeEnum.READ.name(), methodBinding);
+				} else if (RestOperationTypeEnum.READ.equals(restOperationType)
+						&& ((ReadMethodBinding) methodBinding).isVread()) {
+					map.put(resourceName, RestOperationTypeEnum.VREAD.name(), methodBinding);
+				}
+			}
+		}
+		return map;
+	}
+
 	@Nonnull
 	protected String createResourceDescription(
 			CapabilityStatement.CapabilityStatementRestResourceComponent theResource) {
@@ -674,11 +779,12 @@ protected void addSearchOperation(
 			final Operation operation,
 			final FhirContext ctx,
 			final String resourceType,
-			final CapabilityStatement.CapabilityStatementRestResourceComponent nextResource) {
+			final CapabilityStatement.CapabilityStatementRestResourceComponent nextResource,
+			final BaseMethodBinding baseMethodBinding) {
 		operation.addTagsItem(resourceType);
 		operation.setDescription("This is a search type");
 		operation.setSummary("search-type: Search for " + resourceType + " instances");
-		addFhirResourceResponse(ctx, openApi, operation, null);
+		addFhirResourceResponse(ctx, openApi, operation, "Bundle");
 
 		for (final CapabilityStatement.CapabilityStatementRestResourceSearchParamComponent nextSearchParam :
 				nextResource.getSearchParam()) {
@@ -691,6 +797,8 @@ protected void addSearchOperation(
 			parametersItem.setDescription(nextSearchParam.getDocumentation());
 			parametersItem.setSchema(toSchema(nextSearchParam.getType()));
 		}
+
+		customizeOperation(openApi, operation, baseMethodBinding);
 	}
 
 	private Supplier<IBaseResource> patchExampleSupplier() {