Development

software/core/oqm-core-api/build.gradle

@@ -3,12 +3,12 @@ plugins {
 	id 'io.quarkus'
 	id "io.freefair.lombok" version "9.2.0"
 	id 'jacoco'
-	id 'org.cyclonedx.bom' version '3.2.2'
+	id 'org.cyclonedx.bom' version '3.2.3'
 	id("org.spdx.sbom") version "0.10.0"
 }
 
 group 'com.ebp.openQuarterMaster'
-version '4.4.3'
+version '4.4.4-SNAPSHOT'
 
 repositories {
 	mavenCentral()

software/core/oqm-core-api/clientGen/README.md

@@ -8,7 +8,20 @@
 All commands listed to be run in this directory
 
 
-## 
-
-
+## Running
+
+```bash
+docker run --rm \
+-v ${PWD}:/local \
+openapitools/openapi-generator-cli generate \
+-i /local/openapi.yaml -g jaxrs-cxf-client -o /local/out/jaxrs -c /local/jaxrs-cxf-client-config.json
+```
+
+# References
+
+ - https://openapi-generator.tech
+   - https://openapi-generator.tech/docs/installation#docker
+   - Generators:
+     - https://openapi-generator.tech/docs/generators/java
+     - https://openapi-generator.tech/docs/generators/jaxrs-cxf-client
 

software/core/oqm-core-api/clientGen/jaxrs-cxf-client-config.json

@@ -0,0 +1,3 @@
+{
+	"securityScheme": "JwtAuth"
+}

software/core/oqm-core-api/gradle.properties

@@ -1,7 +1,7 @@
 #Gradle properties
 quarkusPluginId=io.quarkus
-quarkusPluginVersion=3.31.1
-quarkusPlatformVersion=3.31.1
+quarkusPluginVersion=3.34.2
+quarkusPlatformVersion=3.34.2
 quarkusPlatformGroupId=io.quarkus
 quarkusPlatformArtifactId=quarkus-universe-bom
 org.gradle.logging.level=INFO

software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/config/CoreApiInteractingEntity.java

@@ -9,6 +9,7 @@
 import org.bson.types.ObjectId;
 import org.eclipse.microprofile.config.inject.ConfigProperty;
 import org.eclipse.microprofile.jwt.JsonWebToken;
+import org.eclipse.microprofile.openapi.annotations.media.Schema;
 import tech.ebp.oqm.core.api.model.object.interactingEntity.InteractingEntity;
 import tech.ebp.oqm.core.api.model.object.interactingEntity.InteractingEntityType;
 
@@ -18,10 +19,11 @@
 @Singleton
 @NoArgsConstructor
 @BsonDiscriminator
+@Schema(title = "CoreApiInteractingEntity", description = "The entity for the core API interacting entity. Used for internal actions, such as schema upgrades and marking as expired.")
 public class CoreApiInteractingEntity extends InteractingEntity {
 
 	/**
-	 * Don't change this. We ue this very specific ObjectId to identify the Base Station's specific entry in the db.
+	 * Don't change this. We use this very specific ObjectId to identify the Base Station's specific entry in the db.
 	 */
 	public static final ObjectId BS_ID = new ObjectId("00000000AAAAAAAAAAFFFFFF");
 
@@ -42,6 +44,7 @@ public String getName() {
 
 	@JsonProperty(access = JsonProperty.Access.READ_ONLY)
 	@Override
+	@Schema(constValue = "CORE_API", readOnly = true, required = true, examples = "CORE_API")
 	public InteractingEntityType getType() {
 		return InteractingEntityType.CORE_API;
 	}

software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/config/OpenApiTweaks.java

@@ -0,0 +1,122 @@
+package tech.ebp.oqm.core.api.config;
+
+import io.quarkus.smallrye.openapi.OpenApiFilter;
+import lombok.extern.slf4j.Slf4j;
+import org.eclipse.microprofile.openapi.OASFactory;
+import org.eclipse.microprofile.openapi.OASFilter;
+import org.eclipse.microprofile.openapi.models.OpenAPI;
+import org.eclipse.microprofile.openapi.models.media.Schema;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Tweaks the openapi schema. Used to hard override certain schemas.
+ * <p>
+ * <a href="https://quarkus.io/guides/openapi-swaggerui#enhancing-the-openapi-schema-with-filters">Quarkus guide section</a>
+ */
+@Slf4j
+@OpenApiFilter(stages = {OpenApiFilter.RunStage.BUILD, OpenApiFilter.RunStage.RUNTIME_STARTUP, OpenApiFilter.RunStage.RUNTIME_PER_REQUEST})
+public class OpenApiTweaks implements OASFilter {
+
+	private static Map<String, Schema> getSchemaOverrides(Map<String, Schema> existingSchemas) {
+		return new HashMap<>() {{
+			{// ObjectId
+				Schema objectIdSchema = OASFactory.createSchema();
+				objectIdSchema.setComment("Hex string representation of a MongoDB ObjectId");
+				objectIdSchema.setType(List.of(Schema.SchemaType.STRING));
+				objectIdSchema.setFormat("objectId");
+				objectIdSchema.setPattern("^[0-9a-fA-F]{24}$");
+				objectIdSchema.setExamples(List.of("null", "5f9222222222222222222222"));
+				put("ObjectId", objectIdSchema);
+			}
+			{// Currency
+				Schema objectIdSchema = OASFactory.createSchema();
+				objectIdSchema.setComment("Currency code from ISO 4217 / Java Currency");
+				objectIdSchema.setType(List.of(Schema.SchemaType.STRING));
+				objectIdSchema.setFormat("currency code");
+				objectIdSchema.setExamples(List.of("USD"));
+				put("Currency", objectIdSchema);
+			}
+			{// Unit
+				Schema unitSchema = OASFactory.createSchema();
+				unitSchema.setTitle("Unit");
+				unitSchema.setComment("Unit of measurement");
+				unitSchema.setType(List.of(Schema.SchemaType.OBJECT));
+
+				{
+					Schema nameSchema = OASFactory.createSchema();
+					nameSchema.type(List.of(Schema.SchemaType.STRING));
+					nameSchema.setReadOnly(true);
+					nameSchema.description("Name of the unit in 'normal' terms. Derived, provided for downstream usage.");
+					nameSchema.setExamples(List.of("Units"));
+
+					unitSchema.addProperty("name", nameSchema);
+				}
+				{
+					Schema symbolSchema = OASFactory.createSchema();
+					symbolSchema.type(List.of(Schema.SchemaType.STRING));
+					symbolSchema.setReadOnly(true);
+					symbolSchema.description("The symbol of the unit, as in 5{symbol}. Derived, provided for downstream usage.");
+					symbolSchema.setExamples(List.of("units"));
+
+					unitSchema.addProperty("symbol", symbolSchema);
+				}
+				{
+					Schema stringSchema = OASFactory.createSchema();
+					stringSchema.type(List.of(Schema.SchemaType.STRING));
+					stringSchema.description(
+						"The string representation of the unit, used in de/serialization. Is the only required field, the others are derived from the deserialized "
+						+ "unit.");
+					stringSchema.setExamples(List.of("units"));
+					unitSchema.addProperty("string", stringSchema);
+				}
+				unitSchema.setRequired(List.of("string"));
+				put("UnitObject", unitSchema); //when Unit<?>
+				put("UnitQuantity", unitSchema); //when Unit<?>?
+				put("Unit", unitSchema); //when Unit
+			}
+			{
+				Schema monetaryAmountSchema = OASFactory.createSchema();
+				monetaryAmountSchema.setComment("An amount of currency");
+				monetaryAmountSchema.setType(List.of(Schema.SchemaType.OBJECT));
+
+				{
+					Schema numberSchema = OASFactory.createSchema();
+					numberSchema.type(List.of(Schema.SchemaType.NUMBER));
+					numberSchema.description("The amount of the currency..");
+					numberSchema.setExamples(List.of("0.00", "0", "5"));
+
+					monetaryAmountSchema.addProperty("number", numberSchema);
+				}
+
+				monetaryAmountSchema.addProperty("currency", this.get("Currency"));
+
+				monetaryAmountSchema.setRequired(List.of("currency", "number"));
+				put("MonetaryAmount", monetaryAmountSchema);
+			}
+			{// Color
+				Schema colorSchema = OASFactory.createSchema();
+				colorSchema.setComment("A hex string representing a color.");
+				colorSchema.setType(List.of(Schema.SchemaType.STRING));
+				colorSchema.setFormat("Color");
+				colorSchema.setPattern("^#?([0-9a-f]{6}|[0-9a-f]{3})$");
+				colorSchema.setExamples(List.of("#FFFFFF"));
+				put("Color", colorSchema);
+			}
+		}};
+	}
+
+	@Override
+	public void filterOpenAPI(OpenAPI openAPI) {
+		log.info("Running OpenApiTweaks filter");
+
+		Map<String, Schema> schemas = new HashMap<>(openAPI.getComponents().getSchemas());
+		schemas.putAll(getSchemaOverrides(schemas));
+		openAPI.getComponents().setSchemas(schemas);
+
+		log.debug("Done OpenApiTweaks filter");
+	}
+
+}

software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/interfaces/endpoints/MainFileObjectProvider.java

@@ -8,6 +8,7 @@
 import lombok.NoArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.bson.types.ObjectId;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
 import tech.ebp.oqm.core.api.interfaces.endpoints.media.FileGet;
 import tech.ebp.oqm.core.api.model.object.FileMainObject;
 import tech.ebp.oqm.core.api.model.object.MainObject;
@@ -34,18 +35,18 @@
 @NoArgsConstructor
 public abstract class MainFileObjectProvider<T extends FileMainObject, U extends FileUploadBody, S extends FileSearchObject<T>, G extends MainObject & FileGet> extends ObjectProvider {
 
-
+	@Parameter(description = "The OQM database id or name to use for this request.")
 	@Getter
 	@PathParam("oqmDbIdOrName")
 	String oqmDbIdOrName;
 
 	public abstract MongoHistoriedFileService<T, U, S, G> getFileService();
 
-	protected Response.ResponseBuilder getSearchResponseBuilder(
+	protected SearchResult<G> getSearchResponseBuilder(
 		String oqmDbIdOrName,
 		S searchObject
 	) {
-		return this.getSearchResultResponseBuilder(this.getFileService().search(oqmDbIdOrName, searchObject));
+		return this.getFileService().search(oqmDbIdOrName, searchObject);
 	}
 
 	//<editor-fold desc="CRUD operations">
@@ -82,12 +83,12 @@ protected Response.ResponseBuilder getSearchResponseBuilder(
 	//	)
 	//	@Produces(MediaType.APPLICATION_JSON)
 	//	@RolesAllowed(UserRoles.INVENTORY_VIEW)
-	public Response search(
+	public SearchResult<G> search(
 		//		@BeanParam
 		S searchObject
 	) {
 		//TODO:: this should produce results of the G type, not T
-		return this.getSearchResponseBuilder(this.getOqmDbIdOrName(), searchObject).build();
+		return this.getSearchResponseBuilder(this.getOqmDbIdOrName(), searchObject);
 	}
 
 	protected abstract T getFileObjFromUpload(U upload);
@@ -114,16 +115,19 @@ public Response search(
 	//	@RolesAllowed(Roles.INVENTORY_ADMIN)
 	//	@Consumes(MediaType.MULTIPART_FORM_DATA)
 	//	@Produces(MediaType.APPLICATION_JSON)
-	public Response add(
+	public G add(
 		//@BeanParam
 		U body
 	) throws IOException {
-		return Response.ok(this.getFileService().add(
+		return this.getFileService().fileObjToGet(
 			this.getOqmDbIdOrName(),
-			this.getFileObjFromUpload(body),
-			body,
-			this.getInteractingEntity()
-		)).build();
+			this.getFileService().add(
+				this.getOqmDbIdOrName(),
+				this.getFileObjFromUpload(body),
+				body,
+				this.getInteractingEntity()
+			)
+		);
 	}
 
 	//	@Path("{id}")
@@ -160,7 +164,7 @@ public Response add(
 	//	@RolesAllowed(UserRoles.INVENTORY_VIEW)
 	public G get(
 		//		@PathParam("id")
-		String id
+		ObjectId id
 	) {
 		log.info("Retrieving object with id {}", id);
 		return this.getFileService().getObjGet(this.getOqmDbIdOrName(), id);
@@ -201,7 +205,7 @@ public G get(
 	//	@Produces(MediaType.APPLICATION_JSON)
 	public Integer updateFile(
 		//		@PathParam("id")
-		String id,
+		ObjectId id,
 		//		@BeanParam
 		U body
 	) throws IOException {
@@ -210,7 +214,7 @@ public Integer updateFile(
 
 	public G updateObj(
 		//		@PathParam("id")
-		String id,
+		ObjectId id,
 		//		@BeanParam
 		ObjectNode updates
 	) {
@@ -226,7 +230,7 @@ public G updateObj(
 		);
 	}
 
-	protected <A> A getRevision(String id, String revision, Class<A> aClass) throws IOException {
+	protected <A> A getRevision(ObjectId id, String revision, Class<A> aClass) throws IOException {
 		int revisionNum;
 		if ("latest".equalsIgnoreCase(revision)) {
 			revisionNum = this.getFileService().getLatestVersionNum(this.getOqmDbIdOrName(), id);
@@ -278,7 +282,7 @@ protected <A> A getRevision(String id, String revision, Class<A> aClass) throws
 	//	@RolesAllowed(UserRoles.INVENTORY_VIEW)
 	public FileMetadata getRevision(
 		//		@PathParam("id")
-		String id,
+		ObjectId id,
 		//		@PathParam("rev")
 		String revision
 	) throws IOException {
@@ -321,7 +325,7 @@ public FileMetadata getRevision(
 	//	@RolesAllowed(UserRoles.INVENTORY_VIEW)
 	public Response getRevisionData(
 		//		@PathParam("id")
-		String id,
+		ObjectId id,
 		//		@PathParam("rev")
 		String revision
 	) throws IOException {
@@ -374,10 +378,10 @@ public Response getRevisionData(
 	//	@RolesAllowed(Roles.INVENTORY_EDIT)
 	public G remove(
 		//		@PathParam("id")
-		String id
+		ObjectId id
 	) {
 		log.info("Retrieving object with id {}", id);
-		return this.getFileService().removeFile(this.getOqmDbIdOrName(), null, new ObjectId(id), this.getInteractingEntity());
+		return this.getFileService().removeFile(this.getOqmDbIdOrName(), null, id, this.getInteractingEntity());
 	}
 
 	//</editor-fold>
@@ -411,18 +415,17 @@ public G remove(
 	//	)
 	//	@Produces(MediaType.APPLICATION_JSON)
 	//	@RolesAllowed(Roles.INVENTORY_VIEW)
-	public Response getHistoryForObject(
+	public SearchResult<ObjectHistoryEvent> getHistoryForObject(
 //		@PathParam("id")
-		String id,
+		ObjectId id,
 		//		@BeanParam
 		HistorySearch searchObject
 	) {
 		log.info("Retrieving specific {} history with id {} from REST interface", this.getFileService().getClazz().getSimpleName(), id);
 
-		searchObject.setObjectId(new ObjectId(id));
+		searchObject.setObjectId(id);
 
-		SearchResult<ObjectHistoryEvent> searchResult = this.getFileService().getFileObjectService().searchHistory(this.getOqmDbIdOrName(), searchObject, false);
-		return this.getSearchResultResponseBuilder(searchResult).build();
+		return this.getFileService().getFileObjectService().searchHistory(this.getOqmDbIdOrName(), searchObject, false);
 	}
 
 	//	@GET