100% open-source IoT Platform - Integrate your devices, add intelligence, build custom apps
Java asset-managementbuildingdashboarddataplatformdevice-managementedge-computingenergyenergy-managementenergy-monitorfleet-managementfleet-telematicsiotiot-applicationiot-platformmodbusmqttmqtt-brokerota-updaterules-enginesmartcity
Improve OpenAPI documentation and machine usability (#3120)
Wouter Bornb1cd7c51cd69
diff --git a/manager/src/main/resources/openapi-base.yaml b/manager/src/main/resources/openapi-base.yamlindex 1b7fbd2e9..974547073 100644--- a/manager/src/main/resources/openapi-base.yaml+++ b/manager/src/main/resources/openapi-base.yaml@@ -5,6 +5,11 @@ info:version: 3.0.0description: >-This is the documentation for the OpenRemote Manager HTTP API.+ The `realm` server variable selects the request realm. Operations that show+ the `openid` security requirement need an OAuth 2 access token; operations+ without that requirement support anonymous access, although the returned+ data can still be limited to public resources. Unless an operation documents+ another schema, error responses use a plain-text body.Please see the [documentation](https://docs.openremote.io) for more info.contact:email: [email protected]@@ -18,9 +23,6 @@ servers:realm:default: master-security:- - openid: []-components:securitySchemes:openid:diff --git a/model/src/main/java/org/openremote/model/alarm/Alarm.java b/model/src/main/java/org/openremote/model/alarm/Alarm.javaindex 17c18db25..7060af8dd 100644--- a/model/src/main/java/org/openremote/model/alarm/Alarm.java+++ b/model/src/main/java/org/openremote/model/alarm/Alarm.java@@ -20,8 +20,10 @@package org.openremote.model.alarm;import com.fasterxml.jackson.annotation.JsonCreator;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.validation.constraints.NotNull;+@Schema(description = "Operational alarm submitted to or returned by the alarm service.")public class Alarm {public enum Source {MANUAL,@@ -50,25 +52,33 @@ public class Alarm {public static final String HEADER_SOURCE_ID = Alarm.class.getName() + ".SOURCEID";@NotNull+ @Schema(description = "Short human-readable alarm title.", example = "Temperature threshold exceeded")protected String title;+ @Schema(description = "Detailed alarm message.", example = "Boiler room temperature reached 42 °C.")protected String content;@NotNull+ @Schema(description = "Operational impact of the alarm.")protected Severity severity;@NotNull+ @Schema(description = "Current alarm workflow state.")protected Status status;+ @Schema(description = "Identity-provider user assigned to handle the alarm.", example = "2f1c17e5-72b8-4dbe-9f8d-c49e66f82e10")protected String assigneeId;@NotNull+ @Schema(description = "Realm that owns the alarm.", example = "building")protected String realm;@NotNull+ @Schema(description = "Identifier of the rule, user, or system component that created the alarm.", accessMode = Schema.AccessMode.READ_ONLY)protected String sourceId;@NotNull+ @Schema(description = "Kind of actor that created the alarm.", accessMode = Schema.AccessMode.READ_ONLY)protected Source source;@JsonCreatordiff --git a/model/src/main/java/org/openremote/model/alarm/AlarmResource.java b/model/src/main/java/org/openremote/model/alarm/AlarmResource.javaindex e1297850e..393711818 100644--- a/model/src/main/java/org/openremote/model/alarm/AlarmResource.java+++ b/model/src/main/java/org/openremote/model/alarm/AlarmResource.java@@ -20,14 +20,17 @@package org.openremote.model.alarm;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.enums.Explode;+import io.swagger.v3.oas.annotations.enums.ParameterStyle;import io.swagger.v3.oas.annotations.media.ArraySchema;import io.swagger.v3.oas.annotations.media.Content;import io.swagger.v3.oas.annotations.media.ExampleObject;import io.swagger.v3.oas.annotations.media.Schema;import io.swagger.v3.oas.annotations.parameters.RequestBody;-import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.Constants;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.annotation.security.RolesAllowed;@@ -36,60 +39,103 @@ import jakarta.ws.rs.*;import java.util.List;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.*;+import static org.openremote.model.http.OpenApiExamples.ALARM_ASSET_LINK_INVALID_MULTIPLE_ALARMS;+import static org.openremote.model.http.OpenApiExamples.ALARM_ASSET_LINK_MULTIPLE;+import static org.openremote.model.http.OpenApiExamples.ALARM_ASSET_LINK_SINGLE;+import static org.openremote.model.http.OpenApiExamples.ALARM_CREATE;-@Tag(name = "Alarm", description = "Operations on alarms")+@Tag(name = "Alarm", description = "Create, query, maintain, and associate alarms with assets")@Path("alarm")public interface AlarmResource {@GET@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ALARMS_ROLE})- @Operation(operationId = "getAlarms", summary = "Retrieve all alarms or a subset using filter criteria")- SentAlarm[] getAlarms(@BeanParam RequestParams requestParams, @QueryParam("realm") String realm,- @QueryParam("status") Alarm.Status status, @QueryParam("assetId") String assetId,- @QueryParam("assigneeId") String assigneeId);+ @Operation(operationId = "getAlarms", summary = "Retrieve all alarms or a subset using filter criteria",+ description = "Returns alarms in the requested accessible realm, optionally filtered by status, linked asset, or assignee. When realm is omitted, the authenticated realm is used.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ SentAlarm[] getAlarms(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM + " Defaults to the authenticated realm.", example = EXAMPLE_REALM) @QueryParam("realm") String realm,+ @Parameter(description = "Alarm lifecycle status to match.", example = "OPEN") @QueryParam("status") Alarm.Status status,+ @Parameter(description = "Return alarms linked to this asset.", example = EXAMPLE_ASSET_ID) @QueryParam("assetId") String assetId,+ @Parameter(description = "Return alarms assigned to this identity-provider user.", example = EXAMPLE_USER_ID) @QueryParam("assigneeId") String assigneeId);@POST@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ALARMS_ROLE})- @Operation(operationId = "createAlarm", summary = "Create an alarm")- SentAlarm createAlarm(@BeanParam RequestParams requestParams, @RequestBody Alarm alarm, @QueryParam("assetIds") List<String> assetIds);+ @Operation(operationId = "createAlarm", summary = "Create an alarm",+ description = "Creates a manual alarm in an accessible realm and optionally links it to the supplied asset IDs. The authenticated user or client becomes the alarm source.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ SentAlarm createAlarm(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Alarm to create. The source and sourceId are assigned from the authenticated caller.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = Alarm.class),+ examples = @ExampleObject(name = "High temperature alarm", summary = "Create an open high-severity alarm", value = ALARM_CREATE))) Alarm alarm,+ @Parameter(description = "Asset IDs to link to the new alarm. Repeat the query parameter for multiple assets.", example = EXAMPLE_ASSET_ID,+ style = ParameterStyle.FORM, explode = Explode.TRUE) @QueryParam("assetIds") List<String> assetIds);@DELETE@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ALARMS_ROLE})- @Operation(operationId = "removeAlarms", summary = "Remove alarms")- void removeAlarms(@BeanParam RequestParams requestParams, @RequestBody List<Long> ids);+ @Operation(operationId = "removeAlarms", summary = "Remove alarms",+ description = "Permanently removes all alarms identified by the request body after verifying access to every alarm's realm.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ void removeAlarms(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Numeric IDs of the alarms to remove.") List<Long> ids);@GET@Path("{alarmId}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ALARMS_ROLE})- @Operation(operationId = "getAlarm", summary = "Retrieve an alarm")- SentAlarm getAlarm(@BeanParam RequestParams requestParams, @PathParam("alarmId") Long alarmId);+ @Operation(operationId = "getAlarm", summary = "Retrieve an alarm",+ description = "Returns one alarm when its realm is active and accessible to the authenticated user.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFound+ SentAlarm getAlarm(@BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric alarm identifier.", example = "1234") @PathParam("alarmId") Long alarmId);@PUT@Path("{alarmId}")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ALARMS_ROLE})- @Operation(operationId = "updateAlarm", summary = "Update an alarm")- void updateAlarm(@BeanParam RequestParams requestParams, @PathParam("alarmId") Long alarmId, @RequestBody SentAlarm alarm);+ @Operation(operationId = "updateAlarm", summary = "Update an alarm",+ description = "Updates the mutable state of an existing alarm after verifying access to its current realm.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.NotFound+ void updateAlarm(@BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric alarm identifier.", example = "1234") @PathParam("alarmId") Long alarmId,+ @RequestBody(required = true, description = "Complete updated alarm state.") SentAlarm alarm);@DELETE@Path("{alarmId}")@RolesAllowed({Constants.WRITE_ALARMS_ROLE})- @Operation(operationId = "removeAlarm", summary = "Remove an alarm")- void removeAlarm(@BeanParam RequestParams requestParams, @PathParam("alarmId") Long alarmId);+ @Operation(operationId = "removeAlarm", summary = "Remove an alarm",+ description = "Permanently removes one alarm after verifying access to its realm.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ void removeAlarm(@BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric alarm identifier.", example = "1234") @PathParam("alarmId") Long alarmId);@GET@Path("{alarmId}/assets")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ALARMS_ROLE})- @Operation(operationId = "getAssetLinks", summary = "Retrieve the asset links of an alarm")- List<AlarmAssetLink> getAssetLinks(@BeanParam RequestParams requestParams, @PathParam("alarmId") Long alarmId,- @QueryParam("realm") String realm);+ @Operation(operationId = "getAssetLinks", summary = "Retrieve the asset links of an alarm",+ description = "Returns links from the alarm to assets in the explicitly supplied accessible realm.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFound+ List<AlarmAssetLink> getAssetLinks(@BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric alarm identifier.", example = "1234") @PathParam("alarmId") Long alarmId,+ @Parameter(description = REALM, example = EXAMPLE_REALM, required = true) @QueryParam("realm") String realm);@PUT@Path("assets")@@ -103,19 +149,16 @@ public interface AlarmResource {The request body is a list for backward compatibility, but this operation now has single-alarm semantics:every item must contain the same `id.realm` and the same `id.alarmId`. The alarm must exist in that realm,- every asset must exist in the same realm, and the authenticated user must have access to that realm.+ every asset must exist in the same realm, and the authenticated user must have access to that realm. Requests+ containing mixed alarm IDs or realms are rejected as bad requests.Existing links are left unchanged; duplicate links in the request or links that already exist are ignored.This operation does not remove existing links from the alarm.- """,- responses = {- @ApiResponse(responseCode = "204", description = "Asset links were added, or already existed"),- @ApiResponse(responseCode = "400", description = "Invalid request body, multiple alarm IDs or realms were provided, or the alarm/assets are not all in the same realm"),- @ApiResponse(responseCode = "401", description = "Authentication is required"),- @ApiResponse(responseCode = "403", description = "The authenticated user is not allowed to write alarms in the requested realm"),- @ApiResponse(responseCode = "404", description = "The alarm or one or more assets do not exist")- }+ """)+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFoundvoid setAssetLinks(@BeanParam RequestParams requestParams,@RequestBody(@@ -128,61 +171,17 @@ public interface AlarmResource {@ExampleObject(name = "Single asset link",summary = "Link one asset to one alarm",- value = """- [- {- "id": {- "realm": "building",- "alarmId": 1234,- "assetId": "7A6p4AnLTkKxJUCQAAABAA"- }- }- ]- """+ value = ALARM_ASSET_LINK_SINGLE),@ExampleObject(name = "Multiple asset links",summary = "Link multiple assets to the same alarm",- value = """- [- {- "id": {- "realm": "building",- "alarmId": 1234,- "assetId": "7A6p4AnLTkKxJUCQAAABAA"- }- },- {- "id": {- "realm": "building",- "alarmId": 1234,- "assetId": "2Qjr4AnLTkKxJUCQAAACAA"- }- }- ]- """+ value = ALARM_ASSET_LINK_MULTIPLE),@ExampleObject(name = "Invalid multiple alarms",summary = "Rejected because the request targets more than one alarm",- value = """- [- {- "id": {- "realm": "building",- "alarmId": 1234,- "assetId": "7A6p4AnLTkKxJUCQAAABAA"- }- },- {- "id": {- "realm": "building",- "alarmId": 5678,- "assetId": "2Qjr4AnLTkKxJUCQAAACAA"- }- }- ]- """+ value = ALARM_ASSET_LINK_INVALID_MULTIPLE_ALARMS)})diff --git a/model/src/main/java/org/openremote/model/apps/AppResource.java b/model/src/main/java/org/openremote/model/apps/AppResource.javaindex d9cedba59..d516f5611 100644--- a/model/src/main/java/org/openremote/model/apps/AppResource.java+++ b/model/src/main/java/org/openremote/model/apps/AppResource.java@@ -25,13 +25,14 @@ import jakarta.ws.rs.BeanParam;import jakarta.ws.rs.GET;import jakarta.ws.rs.Path;import jakarta.ws.rs.Produces;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import java.util.Map;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;-@Tag(name = "UI Apps", description = "Operations on UI apps")+@Tag(name = "UI Apps", description = "Discover installed Manager applications and load their public client configuration")@Path("apps")public interface AppResource {@@ -40,7 +41,10 @@ public interface AppResource {*/@GET@Produces(APPLICATION_JSON)- @Operation(operationId = "getApps", summary = "Retrieve a list of the available applications")+ @Operation(operationId = "getApps", summary = "Retrieve a list of the available applications",+ description = "Returns the identifiers of applications installed in the Manager web root.")+ @OpenApiResponses.Ok+ @OpenApiResponses.ServerErrorString[] getApps(@BeanParam RequestParams requestParams);/**@@ -49,7 +53,10 @@ public interface AppResource {@GET@Produces(APPLICATION_JSON)@Path("info")- @Operation(operationId = "getAppInfos", summary = "Retrieve the info of the available applications")+ @Operation(operationId = "getAppInfos", summary = "Retrieve the info of the available applications",+ description = "Loads each installed application's info.json file and returns the documents keyed by application identifier.")+ @OpenApiResponses.Ok+ @OpenApiResponses.ServerErrorMap<String, Object> getAppInfos(@BeanParam RequestParams requestParams);/**@@ -58,6 +65,10 @@ public interface AppResource {@GET@Produces(APPLICATION_JSON)@Path("consoleConfig")- @Operation(operationId = "getConsoleConfig", summary = "Retrieve the console configuration")+ @Operation(operationId = "getConsoleConfig", summary = "Retrieve the console configuration",+ description = "Loads the public console_config.json document used to configure console clients before sign-in.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFound+ @OpenApiResponses.ServerErrorObject getConsoleConfig(@BeanParam RequestParams requestParams);}diff --git a/model/src/main/java/org/openremote/model/asset/Asset.java b/model/src/main/java/org/openremote/model/asset/Asset.javaindex 6815a9ee5..cfe1d5f4d 100644--- a/model/src/main/java/org/openremote/model/asset/Asset.java+++ b/model/src/main/java/org/openremote/model/asset/Asset.java@@ -28,6 +28,7 @@ import com.fasterxml.jackson.databind.JsonMappingException;import com.fasterxml.jackson.databind.annotation.JsonTypeIdResolver;import com.fasterxml.jackson.databind.deser.ResolvableDeserializer;import com.fasterxml.jackson.databind.deser.std.StdDeserializer;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.persistence.Table;import jakarta.persistence.*;import jakarta.validation.Valid;@@ -232,6 +233,7 @@ import static jakarta.persistence.DiscriminatorType.STRING;@DynamicUpdate@TsIgnoreTypeParams@SuppressWarnings("unchecked")+@Schema(description = "Polymorphic OpenRemote asset. The type discriminator selects a registered asset subtype; attributes are keyed by attribute name.")public abstract class Asset<T extends Asset<?>> implements IdentifiableEntity<T>, AssetInfo {private static final java.util.regex.Pattern ASSET_ID_PATTERN = java.util.regex.Pattern.compile(Constants.ASSET_ID_REGEXP);@@ -287,45 +289,55 @@ public abstract class Asset<T extends Asset<?>> implements IdentifiableEntity<T>@Id @HibernateUniqueIdentifierTypeAssignable@Column(name = "ID", length = 22, columnDefinition = "char(22)")@Pattern(regexp = Constants.ASSET_ID_REGEXP, message = "{Asset.id.Pattern}")+ @Schema(description = "Stable 22-character asset identifier. Omit when creating an asset.", example = "7A6p4AnLTkKxJUCQAAABAA")protected String id;@Version@Min(value = 0L, message = "{Asset.version.Min}")@Column(name = "VERSION", nullable = false)+ @Schema(description = "Optimistic-lock version. Omit when creating an asset and preserve the latest value when updating it.", example = "3")protected long version;@Column(name = "CREATED_ON", updatable = false, nullable = false, columnDefinition = "TIMESTAMP WITH TIME ZONE")@org.hibernate.annotations.CreationTimestamp+ @Schema(description = "Server-assigned asset creation time.", accessMode = Schema.AccessMode.READ_ONLY, example = "2026-01-01T00:00:00Z")protected Instant createdOn;@NotBlank(message = "{Asset.name.NotBlank}")@Size(min = 1, max = 1023, message = "{Asset.name.Size}")@Column(name = "NAME", nullable = false, length = 1023)+ @Schema(description = "Human-readable asset name.", example = "Boiler room sensor")protected String name;@Column(name = "ACCESS_PUBLIC_READ", nullable = false)+ @Schema(description = "Allows anonymous callers to read this asset where an endpoint supports public access.", example = "false")protected boolean accessPublicRead;@Column(name = "PARENT_ID", length = 22, columnDefinition = "char(22)")@Pattern(regexp = Constants.ASSET_ID_REGEXP, message = "{Asset.parentId.Pattern}")+ @Schema(description = "Parent asset identifier. Omit for a root asset.", example = "1ZyG7BmsTQ2cGmbuaMsi0A")protected String parentId;@NotBlank(message = "{Asset.realm.NotBlank}")@Size(min = 1, max = 255, message = "{Asset.realm.Size}")@Column(name = "REALM", nullable = false, updatable = false)+ @Schema(description = "Realm that owns the asset; immutable after creation.", example = "building")protected String realm;@Column(name = "TYPE", nullable = false, updatable = false, insertable = false)+ @Schema(description = "Registered asset subtype discriminator.", example = "ThingAsset")protected String type = getClass().getSimpleName();@Column(name = "PATH", updatable = false, insertable = false, columnDefinition = LTreeType.TYPE)@Type(LTreeType.class)@Generated(event = {EventType.INSERT, EventType.UPDATE})+ @Schema(description = "Ancestor identifiers from the root through the parent.", accessMode = Schema.AccessMode.READ_ONLY)protected String[] path;@Column(name = "ATTRIBUTES")@JdbcTypeCode(SqlTypes.JSON)@Valid+ @Schema(description = "Attributes keyed by attribute name. Each entry contains type, value, timestamp, and optional metadata.")protected AttributeMap attributes;/**diff --git a/model/src/main/java/org/openremote/model/asset/AssetModelResource.java b/model/src/main/java/org/openremote/model/asset/AssetModelResource.javaindex 79adad397..eaa1f63b5 100644--- a/model/src/main/java/org/openremote/model/asset/AssetModelResource.java+++ b/model/src/main/java/org/openremote/model/asset/AssetModelResource.java@@ -21,10 +21,15 @@ package org.openremote.model.asset;import io.swagger.v3.oas.annotations.Operation;import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.responses.ApiResponse;+import io.swagger.v3.oas.annotations.headers.Header;import io.swagger.v3.oas.annotations.tags.Tag;import jakarta.ws.rs.core.Context;import jakarta.ws.rs.core.Request;import org.jboss.resteasy.annotations.cache.Cache;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import org.openremote.model.value.MetaItemDescriptor;import org.openremote.model.value.ValueDescriptor;@@ -35,12 +40,13 @@ import jakarta.ws.rs.core.Response;import java.util.Map;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.EXAMPLE_ASSET_ID;/*** Resource for handling model requests and also providing server side validation of {@link Asset}s*/// TODO: Implement generic Asset<?> validation for assets and agents-@Tag(name = "Asset Model", description = "Operations on asset model resources")+@Tag(name = "Asset Model", description = "Discover asset, attribute-value, and metadata types supported by this Manager or a gateway")@Path("model")public interface AssetModelResource {@@ -53,8 +59,12 @@ public interface AssetModelResource {@GET@Path("assetInfos")@Produces(APPLICATION_JSON)- @Operation(operationId = "getAssetInfos", summary = "Retrieve the asset type information of each available asset type")- AssetTypeInfo[] getAssetInfos(@BeanParam RequestParams requestParams, @QueryParam("parentId") String parentId, @QueryParam("parentType") String parentType);+ @Operation(operationId = "getAssetInfos", summary = "Retrieve the asset type information of each available asset type",+ description = "Returns type metadata from this Manager by default. When parentId identifies an asset below a gateway, the gateway's model is used instead; parentType can provide type context for a new parent that does not yet exist.")+ @OpenApiResponses.Ok+ AssetTypeInfo[] getAssetInfos(@BeanParam RequestParams requestParams,+ @Parameter(description = "Optional parent asset used to select the local or gateway model", example = EXAMPLE_ASSET_ID) @QueryParam("parentId") String parentId,+ @Parameter(description = "Optional parent asset type, primarily for assets that have not been persisted yet", example = "GroupAsset") @QueryParam("parentType") String parentType);/*** Retrieve the specific {@link AssetTypeInfo} of the specified} {@link@@ -66,8 +76,13 @@ public interface AssetModelResource {@GET@Path("assetInfo/{assetType}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getAssetInfo", summary = "Retrieve the asset type information of an asset type")- AssetTypeInfo getAssetInfo(@BeanParam RequestParams requestParams, @QueryParam("parentId") String parentId, @PathParam("assetType") String assetType);+ @Operation(operationId = "getAssetInfo", summary = "Retrieve the asset type information of an asset type",+ description = "Returns metadata for one asset type from this Manager or, when parentId is below a gateway, from that gateway's model. An unknown or gateway-provided type that is not locally available returns no content.")+ @OpenApiResponses.Ok+ @ApiResponse(responseCode = "204", description = "No model information is available for the requested asset type")+ AssetTypeInfo getAssetInfo(@BeanParam RequestParams requestParams,+ @Parameter(description = "Optional parent asset used to select the local or gateway model", example = EXAMPLE_ASSET_ID) @QueryParam("parentId") String parentId,+ @Parameter(description = "Asset type name", example = "ThingAsset", required = true) @PathParam("assetType") String assetType);/*** Retrieve the asset descriptors {@link AssetDescriptor} available in this system or from a {@link@@ -78,8 +93,12 @@ public interface AssetModelResource {@GET@Path("assetDescriptors")@Produces(APPLICATION_JSON)- @Operation(operationId = "getAssetDescriptors", summary = "Retrieve the available asset descriptors")- AssetDescriptor<?>[] getAssetDescriptors(@BeanParam RequestParams requestParams, @QueryParam("parentId") String parentId, @QueryParam("parentType") String parentType);+ @Operation(operationId = "getAssetDescriptors", summary = "Retrieve the available asset descriptors",+ description = "Returns the descriptors used to construct supported asset types, using a gateway model when the optional parent context resolves below a gateway.")+ @OpenApiResponses.Ok+ AssetDescriptor<?>[] getAssetDescriptors(@BeanParam RequestParams requestParams,+ @Parameter(description = "Optional parent asset used to select the local or gateway model", example = EXAMPLE_ASSET_ID) @QueryParam("parentId") String parentId,+ @Parameter(description = "Optional parent asset type, primarily for assets that have not been persisted yet", example = "GroupAsset") @QueryParam("parentType") String parentType);/*** Retrieve value descriptors {@link ValueDescriptor} available in this system or from a {@link@@ -90,8 +109,11 @@ public interface AssetModelResource {@GET@Path("valueDescriptors")@Produces(APPLICATION_JSON)- @Operation(operationId = "getValueDescriptors", summary = "Retrieve the available value descriptors")- Map<String, ValueDescriptor<?>> getValueDescriptors(@BeanParam RequestParams requestParams, @QueryParam("parentId") String parentId);+ @Operation(operationId = "getValueDescriptors", summary = "Retrieve the available value descriptors",+ description = "Returns attribute value descriptors keyed by descriptor name, using a gateway model when parentId resolves below a gateway.")+ @OpenApiResponses.Ok+ Map<String, ValueDescriptor<?>> getValueDescriptors(@BeanParam RequestParams requestParams,+ @Parameter(description = "Optional parent asset used to select the local or gateway model", example = EXAMPLE_ASSET_ID) @QueryParam("parentId") String parentId);/*** Retrieve meta descriptors {@link MetaItemDescriptor} available in this system or from a {@link@@ -102,8 +124,11 @@ public interface AssetModelResource {@GET@Path("metaItemDescriptors")@Produces(APPLICATION_JSON)- @Operation(operationId = "getMetaItemDescriptors", summary = "Retrieve the available meta item descriptors")- Map<String, MetaItemDescriptor<?>> getMetaItemDescriptors(@BeanParam RequestParams requestParams, @QueryParam("parentId") String parentId);+ @Operation(operationId = "getMetaItemDescriptors", summary = "Retrieve the available meta item descriptors",+ description = "Returns attribute metadata descriptors keyed by descriptor name, using a gateway model when parentId resolves below a gateway.")+ @OpenApiResponses.Ok+ Map<String, MetaItemDescriptor<?>> getMetaItemDescriptors(@BeanParam RequestParams requestParams,+ @Parameter(description = "Optional parent asset used to select the local or gateway model", example = EXAMPLE_ASSET_ID) @QueryParam("parentId") String parentId);/*** Retrieve the JSON Schema for a {@link ValueDescriptor} available in this system. A value descriptor schema is only meant to be retrieved@@ -114,6 +139,15 @@ public interface AssetModelResource {@Path("getValueDescriptorSchema")@Produces(APPLICATION_JSON)@Cache(noCache = true)- @Operation(operationId = "getValueDescriptorSchema", summary = "Retrieve the JSON Schema of the specified value descriptor")- Response getValueDescriptorSchema(@QueryParam("name") String name, @Context Request request);+ @Operation(operationId = "getValueDescriptorSchema", summary = "Retrieve the JSON Schema of the specified value descriptor",+ description = "Returns the JSON Schema and a weak ETag for the named value descriptor. Send If-None-Match on later requests to receive 304 when the schema has not changed.")+ @ApiResponse(responseCode = "200", description = "The current JSON Schema",+ headers = @Header(name = "ETag", description = "Weak entity tag identifying this schema version", schema = @Schema(type = "string", example = "W/\"17af8b28\"")),+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(type = "object")))+ @ApiResponse(responseCode = "304", description = "The supplied ETag still identifies the current schema",+ headers = @Header(name = "ETag", description = "Entity tag supplied by the client", schema = @Schema(type = "string")))+ @OpenApiResponses.NotFound+ Response getValueDescriptorSchema(+ @Parameter(description = "Value descriptor name", example = "number", required = true) @QueryParam("name") String name,+ @Context Request request);}diff --git a/model/src/main/java/org/openremote/model/asset/AssetResource.java b/model/src/main/java/org/openremote/model/asset/AssetResource.javaindex daf5eead7..baa91522a 100644--- a/model/src/main/java/org/openremote/model/asset/AssetResource.java+++ b/model/src/main/java/org/openremote/model/asset/AssetResource.java@@ -20,8 +20,14 @@package org.openremote.model.asset;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.enums.Explode;+import io.swagger.v3.oas.annotations.enums.ParameterStyle;+import io.swagger.v3.oas.annotations.media.ArraySchema;import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.ExampleObject;import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.parameters.RequestBody;import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import jakarta.annotation.security.RolesAllowed;@@ -34,6 +40,7 @@ import org.openremote.model.attribute.AttributeRef;import org.openremote.model.attribute.AttributeState;import org.openremote.model.attribute.AttributeWriteResult;import org.openremote.model.http.RequestParams;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.query.AssetQuery;import org.openremote.model.util.TsIgnore;import org.openremote.model.value.MetaItemType;@@ -41,6 +48,8 @@ import org.openremote.model.value.MetaItemType;import java.util.List;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.*;+import static org.openremote.model.http.OpenApiExamples.*;/*** Asset<?> access rules:@@ -67,7 +76,7 @@ import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;* <li>{@link #writeAttributeValue}</li>* </ul>*/-@Tag(name = "Asset", description = "Operations on assets")+@Tag(name = "Asset", description = "Query and manage assets, attributes, hierarchy, and user-to-asset links")@Path("asset")public interface AssetResource {@@ -93,7 +102,11 @@ public interface AssetResource {@Path("user/current")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ASSETS_ROLE})- @Operation(operationId = "getCurrentUserAssets", summary = "Retrieve the linked assets of the currently authenticated user")+ @Operation(operationId = "getCurrentUserAssets", summary = "Retrieve assets accessible to the current user",+ description = "Returns partial linked assets for a restricted user, root assets for an unrestricted realm user, and an empty array for a super user. Attributes and paths are omitted; use getAsset for full details.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequestAsset<?>[] getCurrentUserAssets(@BeanParam RequestParams requestParams);/**@@ -113,11 +126,15 @@ public interface AssetResource {@Path("user/link")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ASSETS_ROLE})- @Operation(operationId = "getUserAssetLinks", summary = "Retrieve links between assets and users")+ @Operation(operationId = "getUserAssetLinks", summary = "Retrieve links between assets and users",+ description = "Returns user-asset links in the required realm, optionally filtered by userId and assetId. Missing users or assets produce an empty result; restricted users cannot call this operation.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequestUserAssetLink[] getUserAssetLinks(@BeanParam RequestParams requestParams,- @QueryParam("realm") String realm,- @QueryParam("userId") String userId,- @QueryParam("assetId") String assetId);+ @Parameter(description = REALM + " Defaults to the authenticated realm.", example = EXAMPLE_REALM) @QueryParam("realm") String realm,+ @Parameter(description = "Only return links for this user.", example = EXAMPLE_USER_ID) @QueryParam("userId") String userId,+ @Parameter(description = "Only return links for this asset.", example = EXAMPLE_ASSET_ID) @QueryParam("assetId") String assetId);/*** Create all of the specified links; they must all be for the same realm and user.@@ -132,8 +149,13 @@ public interface AssetResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "createUserAssetLinks", summary = "Create links between users and assets")- void createUserAssetLinks(@BeanParam RequestParams requestParams, List<UserAssetLink> userAssets);+ @Operation(operationId = "createUserAssetLinks", summary = "Create links between users and assets",+ description = "Creates all supplied links as one operation. Every item must identify the same realm and user, and every referenced realm, user, and asset must exist.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ void createUserAssetLinks(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Links to create. Every item must have the same realm and user ID.") List<UserAssetLink> userAssets);/*** Delete a link between asset and user.@@ -148,11 +170,15 @@ public interface AssetResource {@DELETE@Path("user/link/{realm}/{userId}/{assetId}")@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "deleteUserAssetLink", summary = "Delete a link between an asset and user")+ @Operation(operationId = "deleteUserAssetLink", summary = "Delete a link between an asset and user",+ description = "Removes the link identified by realm, user, and asset. The caller must be allowed to administer asset links in that realm.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequestvoid deleteUserAssetLink(@BeanParam RequestParams requestParams,- @PathParam("realm") String realm,- @PathParam("userId") String userId,- @PathParam("assetId") String assetId);+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId);/*** Delete all of the specified links; they must all be for the same realm and user.@@ -166,18 +192,27 @@ public interface AssetResource {@Path("user/link/delete")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "deleteUserAssetLinks", summary = "Delete user asset links")- void deleteUserAssetLinks(@BeanParam RequestParams requestParams, List<UserAssetLink> userAssets);+ @Operation(operationId = "deleteUserAssetLinks", summary = "Delete user asset links",+ description = "Removes all supplied links. Every item must identify the same realm and user.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ void deleteUserAssetLinks(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Links to remove. Every item must have the same realm and user ID.") List<UserAssetLink> userAssets);@DELETE@Path("user/link/{realm}/{userId}")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "deleteAllUserAssetLinks", summary = "Delete all user asset links")+ @Operation(operationId = "deleteAllUserAssetLinks", summary = "Delete all links for a user",+ description = "Removes every asset link belonging to the user in the requested realm.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequestvoid deleteAllUserAssetLinks(@BeanParam RequestParams requestParams,- @PathParam("realm") String realm,- @PathParam("userId") String userId);+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId);/*** Retrieve the asset. Regular users can only access assets in their authenticated realm, the superuser can access@@ -189,8 +224,14 @@ public interface AssetResource {@Path("{assetId}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ASSETS_ROLE})- @Operation(operationId = "getAsset", summary = "Retrieve an asset")- Asset<?> get(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId);+ @Operation(operationId = "getAsset", summary = "Retrieve an asset",+ description = "Returns a fully loaded asset including its path and attributes. Access is constrained to the caller's realm and, for restricted users, linked assets.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ Asset<?> get(@BeanParam RequestParams requestParams,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId);/*** Same as {@link #get} but only returns a partially loaded asset (no attributes or path)@@ -199,8 +240,14 @@ public interface AssetResource {@Path("partial/{assetId}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ASSETS_ROLE})- @Operation(operationId = "getPartialAsset", summary = "Retrieve a partially loaded asset (no attributes or path)")- Asset<?> getPartial(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId);+ @Operation(operationId = "getPartialAsset", summary = "Retrieve a partially loaded asset",+ description = "Returns the asset identity and properties without loading attributes or path data. The same access rules as getAsset apply.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ Asset<?> getPartial(@BeanParam RequestParams requestParams,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId);/*** Updates the asset. Regular users can only update assets in their authenticated realm, the superuser can update@@ -217,8 +264,18 @@ public interface AssetResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "updateAsset", summary = "Update an asset")- Asset<?> update(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId, Asset<?> asset);+ @Operation(operationId = "updateAsset", summary = "Update an asset",+ description = "Replaces mutable asset data while preserving the path identifier. Realm, parent, restricted-user, and private-metadata rules are validated; disallowed restricted-user fields may be ignored.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @OpenApiResponses.Conflict+ Asset<?> update(@BeanParam RequestParams requestParams,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId,+ @RequestBody(required = true, description = "Complete asset representation to store. The body ID, when present, must match the path ID; type and realm cannot be changed.",+ content = @Content(mediaType = APPLICATION_JSON,+ examples = @ExampleObject(name = "Update an asset", summary = "Rename an asset and update its attribute values", value = ASSET_UPDATE))) Asset<?> asset);/*** Updates an attribute of an asset. Regular users can only update assets in their authenticated realm, the@@ -240,42 +297,71 @@ public interface AssetResource {@Path("{assetId}/attribute/{attributeName}")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "writeAttributeValue", summary = "Write to a single attribute", responses = {- @ApiResponse(description = "The result of the write operation",- content = @Content(mediaType = "application/json",- schema = @Schema(implementation = AttributeWriteResult.class)))})- AttributeWriteResult writeAttributeValue(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId, @PathParam("attributeName") String attributeName, Object value);+ @Operation(operationId = "writeAttributeValue", summary = "Write a value to one asset attribute",+ description = "Submits an asynchronous attribute write using the current server time. The result reports whether the event was accepted, not whether downstream processing ultimately succeeded. Anonymous writes require public-write metadata.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Forbidden+ @OpenApiResponses.NotFound+ @ApiResponse(responseCode = "400", description = "The attribute write failed",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = AttributeWriteResult.class)))+ @ApiResponse(responseCode = "406", description = "The supplied value is not valid for the attribute",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = AttributeWriteResult.class)))+ @ApiResponse(responseCode = "429", description = "The attribute event queue is full; retry the write later",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = AttributeWriteResult.class)))+ AttributeWriteResult writeAttributeValue(@BeanParam RequestParams requestParams,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId,+ @Parameter(description = ATTRIBUTE_NAME, example = EXAMPLE_ATTRIBUTE_NAME) @PathParam("attributeName") String attributeName,+ @RequestBody(required = true, description = "Any JSON value accepted by the attribute's value descriptor. JSON null clears the value.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(nullable = true),+ examples = @ExampleObject(name = "Numeric value", summary = "Write a number attribute", value = ATTRIBUTE_VALUE))) Object value);@PUT//TODO: Using {timestamp:(\\d+)?} does not correctly tokenize when using the assetResource proxy client in Groovy tests.@Path("{assetId}/attribute/{attributeName}/{timestamp}")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "writeAttributeValue", summary = "Write to a single attribute with a timestamp", responses = {- @ApiResponse(- description = "The result of the write operation",- content = @Content(mediaType = "application/json", schema = @Schema(implementation = AttributeWriteResult.class))- )})+ @Operation(operationId = "writeAttributeValueWithTimestamp", summary = "Write a timestamped value to one asset attribute",+ description = "Submits an asynchronous attribute write using the supplied Unix timestamp in milliseconds. The result reports acceptance only; anonymous writes require public-write metadata.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Forbidden+ @OpenApiResponses.NotFound+ @ApiResponse(responseCode = "400", description = "The attribute write failed",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = AttributeWriteResult.class)))+ @ApiResponse(responseCode = "406", description = "The supplied value is not valid for the attribute",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = AttributeWriteResult.class)))+ @ApiResponse(responseCode = "429", description = "The attribute event queue is full; retry the write later",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = AttributeWriteResult.class)))AttributeWriteResult writeAttributeValue(@BeanParam RequestParams requestParams,- @PathParam("assetId") String assetId,- @PathParam("attributeName") String attributeName,- @PathParam("timestamp") Long timestamp,- Object value);+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId,+ @Parameter(description = ATTRIBUTE_NAME, example = EXAMPLE_ATTRIBUTE_NAME) @PathParam("attributeName") String attributeName,+ @Parameter(description = TIMESTAMP, example = EXAMPLE_TIMESTAMP) @PathParam("timestamp") Long timestamp,+ @RequestBody(required = true, description = "Any JSON value accepted by the attribute's value descriptor. JSON null clears the value.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(nullable = true),+ examples = @ExampleObject(name = "Timestamped numeric value", summary = "Write a number with the path timestamp", value = ATTRIBUTE_VALUE))) Object value);@PUT@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@Path("attributes")- @Operation(operationId = "writeAttributeValues", summary = "Update attribute values")- AttributeWriteResult[] writeAttributeValues(@BeanParam RequestParams requestParams, AttributeState[] attributeStates);+ @Operation(operationId = "writeAttributeValues", summary = "Write values to multiple asset attributes",+ description = "Submits a batch of attribute states using current server time and returns one result per input item. Authorization and processing failures are encoded in each AttributeWriteResult rather than returned as an HTTP error.")+ @OpenApiResponses.Ok+ AttributeWriteResult[] writeAttributeValues(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Attribute references and values to write using the current server time.",+ content = @Content(mediaType = APPLICATION_JSON,+ array = @ArraySchema(schema = @Schema(implementation = AttributeState.class)),+ examples = @ExampleObject(name = "Write two attributes", summary = "Update temperature and humidity on one asset", value = ATTRIBUTE_STATES))) AttributeState[] attributeStates);@PUT@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@Path("attributes/timestamp")- @Operation(operationId = "writeAttributeEvents", summary = "Update attribute values with timestamps")- AttributeWriteResult[] writeAttributeEvents(@BeanParam RequestParams requestParams, AttributeEvent[] attributeEvents);+ @Operation(operationId = "writeAttributeEvents", summary = "Write timestamped values to multiple asset attributes",+ description = "Submits a batch of complete attribute events and returns one result per input item. Supplied timestamps are preserved; authorization and processing failures are encoded per result rather than returned as an HTTP error.")+ @OpenApiResponses.Ok+ AttributeWriteResult[] writeAttributeEvents(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Complete attribute events to write, including their timestamps.") AttributeEvent[] attributeEvents);/*** Creates an asset. The identifier value of the asset can be provided, it should be a globally unique string value,@@ -289,8 +375,15 @@ public interface AssetResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "createAsset", summary = "Create an asset")- Asset<?> create(@BeanParam RequestParams requestParams, Asset<?> asset);+ @Operation(operationId = "createAsset", summary = "Create an asset",+ description = "Creates an asset in an accessible realm and returns the persisted representation. The server generates an ID when absent; supplied IDs must be globally unique and 22 characters long.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ Asset<?> create(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Asset to create. Omit id to let the server generate one; realm defaults to the authenticated realm.",+ content = @Content(mediaType = APPLICATION_JSON,+ examples = @ExampleObject(name = "Create a Thing asset", summary = "Create a sensor with temperature and humidity attributes", value = ASSET_CREATE))) Asset<?> asset);/*** Deletes an asset. Regular users can only delete assets in their authenticated realm, the superuser can delete@@ -300,8 +393,14 @@ public interface AssetResource {@DELETE@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "deleteAsset", summary = "Delete assets")- void delete(@BeanParam RequestParams requestParams, @QueryParam("assetId") List<String> assetIds);+ @Operation(operationId = "deleteAsset", summary = "Delete assets",+ description = "Permanently deletes every asset identified by repeated assetId query parameters, subject to realm and restricted-user access rules.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ void delete(@BeanParam RequestParams requestParams,+ @Parameter(description = "Asset IDs to delete. Repeat the query parameter for multiple assets.", example = EXAMPLE_ASSET_ID,+ required = true, style = ParameterStyle.FORM, explode = Explode.TRUE) @QueryParam("assetId") List<String> assetIds);/*** Retrieve assets using an {@link AssetQuery}.@@ -316,8 +415,15 @@ public interface AssetResource {@Path("query")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "queryAssets", summary = "Retrieve assets using a query")- Asset<?>[] queryAssets(@BeanParam RequestParams requestParams, AssetQuery query);+ @Operation(operationId = "queryAssets", summary = "Retrieve assets using a query",+ description = "Executes an AssetQuery after constraining realm and linked-asset access. Anonymous callers receive public-readable assets only; the query select clause controls which fields are populated.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ Asset<?>[] queryAssets(@BeanParam RequestParams requestParams,+ @RequestBody(description = "Optional asset query. An omitted or empty query selects all assets visible to the caller.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = AssetQuery.class),+ examples = @ExampleObject(name = "Find sensors", summary = "Find Thing assets with sensor in their name and select two attributes", value = ASSET_QUERY))) AssetQuery query);/**@@ -334,8 +440,13 @@ public interface AssetResource {@Path("tree")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "queryAssetTree", summary = "Retrieve part of the asset tree using a query, returns an optimized structure for tree display")- AssetTree queryAssetTree(@BeanParam RequestParams requestParams, AssetQuery query);+ @Operation(operationId = "queryAssetTree", summary = "Retrieve an optimized asset tree using a query",+ description = "Applies the same authorization and selection rules as queryAssets, then returns a hierarchy optimized for tree display rather than a flat asset array.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ AssetTree queryAssetTree(@BeanParam RequestParams requestParams,+ @RequestBody(description = "Optional asset query controlling the roots, filters, and fields included in the returned tree.") AssetQuery query);/*** Retrieve the amount of assets using an {@link AssetQuery}.@@ -344,8 +455,13 @@ public interface AssetResource {@Path("count")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "queryCount", summary = "Counts the amount of assets using a query")- Integer queryCount(@BeanParam RequestParams requestParams, AssetQuery query);+ @Operation(operationId = "queryCount", summary = "Count assets using a query",+ description = "Returns only the number of assets matching an AssetQuery after applying the caller's realm, public, and linked-asset access constraints.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ Integer queryCount(@BeanParam RequestParams requestParams,+ @RequestBody(description = "Optional asset query to count. An omitted or empty query counts all assets visible to the caller.") AssetQuery query);/*** Change parent for a set of asset@@ -355,8 +471,15 @@ public interface AssetResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "updateAssetParent", summary = "Update the parent of assets")- void updateParent(@BeanParam RequestParams requestParams, @PathParam("parentAssetId") @NotNull(message = "Parent reference required") String parentId, @QueryParam("assetIds") @Size(min = 1, message = "At least one child to update parent reference") List<String> assetIds);+ @Operation(operationId = "updateAssetParent", summary = "Move assets below a new parent",+ description = "Sets parentAssetId as the parent of every asset listed in repeated assetIds query parameters. Parent and children must satisfy realm, access, and hierarchy constraints.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ void updateParent(@BeanParam RequestParams requestParams,+ @Parameter(description = "Asset that will become the new parent.", example = EXAMPLE_ASSET_ID) @PathParam("parentAssetId") @NotNull(message = "Parent reference required") String parentId,+ @Parameter(description = "Child asset IDs to move. Repeat the query parameter for multiple assets.", example = EXAMPLE_ASSET_ID,+ required = true, style = ParameterStyle.FORM, explode = Explode.TRUE) @QueryParam("assetIds") @Size(min = 1, message = "At least one child to update parent reference") List<String> assetIds);/*** Remove parent reference from each asset referenced in the query parameter assetIds@@ -365,6 +488,12 @@ public interface AssetResource {@Path("/parent")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "deleteAssetsParent", summary = "Delete the parent of assets")- void updateNoneParent(@BeanParam RequestParams requestParams, @QueryParam("assetIds") @Size(min = 1, message = "At least one child to update parent reference") List<String> assetIds);+ @Operation(operationId = "deleteAssetsParent", summary = "Move assets to the realm root",+ description = "Clears the parent reference of every asset listed in repeated assetIds query parameters.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ void updateNoneParent(@BeanParam RequestParams requestParams,+ @Parameter(description = "Asset IDs to move to the realm root. Repeat the query parameter for multiple assets.", example = EXAMPLE_ASSET_ID,+ required = true, style = ParameterStyle.FORM, explode = Explode.TRUE) @QueryParam("assetIds") @Size(min = 1, message = "At least one child to update parent reference") List<String> assetIds);}diff --git a/model/src/main/java/org/openremote/model/asset/agent/AgentResource.java b/model/src/main/java/org/openremote/model/asset/agent/AgentResource.javaindex a7301e06f..56437bc9d 100644--- a/model/src/main/java/org/openremote/model/asset/agent/AgentResource.java+++ b/model/src/main/java/org/openremote/model/asset/agent/AgentResource.java@@ -20,12 +20,16 @@package org.openremote.model.asset.agent;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.parameters.RequestBody;+import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.Constants;import org.openremote.model.asset.Asset;import org.openremote.model.asset.AssetResource;import org.openremote.model.asset.AssetTreeNode;import org.openremote.model.file.FileInfo;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import org.openremote.model.protocol.ProtocolInstanceDiscovery;@@ -33,13 +37,15 @@ import jakarta.annotation.security.RolesAllowed;import jakarta.ws.rs.*;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.*;/*** This resource is for Agent specific tasks like import and discovery; normal asset/attribute CRUD operations should* still use {@link AssetResource}.*/-@Tag(name = "Agent", description = "Operations on agents")+@Tag(name = "Agent", description = "Discover protocol instances and import or discover assets through Agent assets")@Path("agent")public interface AgentResource {/**@@ -55,12 +61,17 @@ public interface AgentResource {@Path("instanceDiscovery/{agentType}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ASSETS_ROLE})- @Operation(operationId = "doProtocolInstanceDiscovery", summary = "Do protocol instance discovery")+ @Operation(operationId = "doProtocolInstanceDiscovery", summary = "Discover protocol instances",+ description = "Runs instance discovery for an agent type and returns candidate Agent assets. parentId selects local versus edge-gateway discovery; non-super users are always constrained to their authenticated realm.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @ApiResponse(responseCode = "415", description = "The selected agent protocol does not support instance discovery")Agent<?, ?, ?>[] doProtocolInstanceDiscovery(@BeanParam RequestParams requestParams,- @QueryParam("parentId") String parentId,- @PathParam("agentType") String agentType,- @QueryParam("realm") String realm+ @Parameter(description = "Optional parent asset used to choose local or edge-gateway discovery.", example = EXAMPLE_ASSET_ID) @QueryParam("parentId") String parentId,+ @Parameter(description = "Registered agent asset type whose protocol supports instance discovery.", example = "HTTPAgent") @PathParam("agentType") String agentType,+ @Parameter(description = REALM + " Non-super users are always restricted to their authenticated realm.", example = EXAMPLE_REALM) @QueryParam("realm") String realm);/**@@ -75,11 +86,16 @@ public interface AgentResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "doProtocolAssetDiscovery", summary = "Do protocol asset discovery")+ @Operation(operationId = "doProtocolAssetDiscovery", summary = "Discover assets through an agent",+ description = "Runs the agent protocol's asset discovery, waits up to ten seconds for results, returns the discovered tree, and asynchronously persists discovered assets below the agent.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @OpenApiResponses.ServerErrorAssetTreeNode[] doProtocolAssetDiscovery(@BeanParam RequestParams requestParams,- @PathParam("agentId") String agentId,- @QueryParam("realm") String realm+ @Parameter(description = "Agent asset that performs discovery.", example = EXAMPLE_ASSET_ID) @PathParam("agentId") String agentId,+ @Parameter(description = REALM + " Non-super users are always restricted to their authenticated realm.", example = EXAMPLE_REALM) @QueryParam("realm") String realm);/**@@ -96,12 +112,18 @@ public interface AgentResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ASSETS_ROLE})- @Operation(operationId = "doProtocolAssetImport", summary = "Do protocol asset import")+ @Operation(operationId = "doProtocolAssetImport", summary = "Import assets through an agent",+ description = "Decodes the supplied FileInfo, asks the agent protocol to import it, persists the returned asset tree below the agent, and returns that tree.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @ApiResponse(responseCode = "405", description = "The selected agent protocol does not support asset import")+ @OpenApiResponses.ServerError// TODO: File upload should use standard multipart mechanismAssetTreeNode[] doProtocolAssetImport(@BeanParam RequestParams requestParams,- @PathParam("agentId") String agentId,- @QueryParam("realm") String realm,- FileInfo fileInfo+ @Parameter(description = "Agent asset that performs the import.", example = EXAMPLE_ASSET_ID) @PathParam("agentId") String agentId,+ @Parameter(description = REALM + " Non-super users are always restricted to their authenticated realm.", example = EXAMPLE_REALM) @QueryParam("realm") String realm,+ @RequestBody(required = true, description = "File metadata and Base64 or text contents in the format understood by the selected agent protocol.") FileInfo fileInfo);}diff --git a/model/src/main/java/org/openremote/model/attribute/Attribute.java b/model/src/main/java/org/openremote/model/attribute/Attribute.javaindex c764a0f56..432b33d2d 100644--- a/model/src/main/java/org/openremote/model/attribute/Attribute.java+++ b/model/src/main/java/org/openremote/model/attribute/Attribute.java@@ -35,6 +35,7 @@ import com.fasterxml.jackson.databind.deser.std.StdDeserializer;import com.fasterxml.jackson.databind.exc.InvalidFormatException;import com.fasterxml.jackson.databind.ser.std.StdSerializer;import com.fasterxml.jackson.databind.type.TypeFactory;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.annotation.Nonnull;import jakarta.validation.Valid;import jakarta.validation.constraints.NotNull;@@ -55,6 +56,7 @@ import java.util.stream.Stream;*/@JsonDeserialize(using = Attribute.AttributeDeserializer.class)@JsonSerialize(using = Attribute.AttributeSerializer.class)+@Schema(description = "Named typed asset value. Attribute JSON includes name, type, value, optional Unix-millisecond timestamp, and optional metadata.")public class Attribute<T> extends AbstractNameValueHolder<T> implements MetaHolder {/**@@ -199,8 +201,10 @@ public class Attribute<T> extends AbstractNameValueHolder<T> implements MetaHold@JsonIgnore@Valid+ @Schema(description = "Optional behavior and integration metadata keyed by meta-item name.")protected MetaMap meta;@JsonInclude(JsonInclude.Include.NON_DEFAULT)+ @Schema(description = "Value timestamp in Unix milliseconds; zero means no explicit timestamp was supplied.", example = "1767225600000")protected long timestamp;Attribute() {diff --git a/model/src/main/java/org/openremote/model/console/ConsoleResource.java b/model/src/main/java/org/openremote/model/console/ConsoleResource.javaindex 65c11fa37..869bb806d 100644--- a/model/src/main/java/org/openremote/model/console/ConsoleResource.java+++ b/model/src/main/java/org/openremote/model/console/ConsoleResource.java@@ -20,9 +20,11 @@package org.openremote.model.console;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.parameters.RequestBody;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.asset.impl.ConsoleAsset;import org.openremote.model.attribute.Attribute;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.validation.Valid;@@ -31,7 +33,7 @@ import jakarta.ws.rs.*;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;-@Tag(name = "Console", description = "Operations on consoles")+@Tag(name = "Console", description = "Register mobile and browser consoles as Console assets")@Path("console")public interface ConsoleResource {@@ -52,6 +54,13 @@ public interface ConsoleResource {@Path("register")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "register", summary = "Create or update the registration for a console")- ConsoleRegistration register(@BeanParam RequestParams requestParams, @NotNull @Valid ConsoleRegistration consoleRegistration);+ @Operation(operationId = "register", summary = "Create or update the registration for a console",+ description = "Creates an anonymous console registration when id is absent, or updates an existing registration when id is present. Authenticated new registrations are linked to the caller; updates require that link. The returned registration contains the durable asset ID for later calls.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ @OpenApiResponses.Conflict+ ConsoleRegistration register(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Console platform, version, display name, and notification-provider registrations. Omit id to create a registration; include the returned id to update it.")+ @NotNull @Valid ConsoleRegistration consoleRegistration);}diff --git a/model/src/main/java/org/openremote/model/dashboard/Dashboard.java b/model/src/main/java/org/openremote/model/dashboard/Dashboard.javaindex 26b55bfd8..fb01acde7 100644--- a/model/src/main/java/org/openremote/model/dashboard/Dashboard.java+++ b/model/src/main/java/org/openremote/model/dashboard/Dashboard.java@@ -1,5 +1,6 @@package org.openremote.model.dashboard;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.persistence.*;import jakarta.validation.Valid;import jakarta.validation.constraints.NotBlank;@@ -14,6 +15,7 @@ import java.util.Objects;@Entity@Table(name = "DASHBOARD")+@Schema(description = "Realm-scoped Manager dashboard with ownership, access policy, and a screen/widget template.")public class Dashboard {@Id @HibernateUniqueIdentifierTypediff --git a/model/src/main/java/org/openremote/model/dashboard/DashboardResource.java b/model/src/main/java/org/openremote/model/dashboard/DashboardResource.javaindex 8dee7b85a..763ff6ed7 100644--- a/model/src/main/java/org/openremote/model/dashboard/DashboardResource.java+++ b/model/src/main/java/org/openremote/model/dashboard/DashboardResource.java@@ -1,17 +1,26 @@package org.openremote.model.dashboard;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.ExampleObject;+import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.parameters.RequestBody;import io.swagger.v3.oas.annotations.tags.Tag;import jakarta.annotation.security.RolesAllowed;import jakarta.validation.Valid;import jakarta.ws.rs.*;import org.openremote.model.Constants;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import org.openremote.model.query.DashboardQuery;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.EXAMPLE_REALM;+import static org.openremote.model.http.OpenApiDescriptions.REALM;+import static org.openremote.model.http.OpenApiExamples.*;-@Tag(name = "Dashboard", description = "Operations on dashboards")+@Tag(name = "Dashboard", description = "Query public or accessible dashboards and manage dashboards for the Insights UI")@Path("dashboard")public interface DashboardResource {@@ -22,8 +31,12 @@ public interface DashboardResource {@GET@Path("all/{realm}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getAllRealmDashboards", summary = "Retrieve all accessible dashboards")- Dashboard[] getAllRealmDashboards(@BeanParam RequestParams requestParams, @PathParam("realm") String realm);+ @Operation(operationId = "getAllRealmDashboards", summary = "Retrieve all accessible dashboards",+ description = "Returns dashboards visible to the caller in the requested realm. Anonymous callers receive public dashboards only; authenticated access also depends on roles, ownership, and linked assets.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ Dashboard[] getAllRealmDashboards(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm);/*** Queries a specific {@link Dashboard} by its ID and realm, if a user has access to it.@@ -32,8 +45,14 @@ public interface DashboardResource {@GET@Path("{realm}/{dashboardId}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getDashboard", summary = "Retrieve a dashboard")- Dashboard get(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("dashboardId") String dashboardId);+ @Operation(operationId = "getDashboard", summary = "Retrieve a dashboard",+ description = "Returns one dashboard only when it is visible to the caller. Inaccessible and nonexistent dashboards both return 404 to avoid disclosing their existence.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ Dashboard get(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = "Dashboard identifier.", example = "operations-overview") @PathParam("dashboardId") String dashboardId);/*** Advanced query endpoint for retrieving {@link Dashboard} from the database.@@ -46,27 +65,58 @@ public interface DashboardResource {@Path("query")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "queryDashboards", summary = "Retrieve dashboards using a query")- Dashboard[] query(@BeanParam RequestParams requestParams, @Valid DashboardQuery dashboardQuery);+ @Operation(operationId = "queryDashboards", summary = "Retrieve dashboards using a query",+ description = "Executes a dashboard query after constraining it to the caller's realm, roles, ownership, and asset access. A missing body uses the request realm and default visibility rules.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ Dashboard[] query(@BeanParam RequestParams requestParams,+ @RequestBody(description = "Optional dashboard filters, realm, access rules, sorting, and pagination. An omitted body uses the request realm and default visibility rules.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = DashboardQuery.class),+ examples = @ExampleObject(name = "Find operations dashboards", summary = "Find public or shared dashboards by name in one realm", value = DASHBOARD_QUERY))) @Valid DashboardQuery dashboardQuery);@POST@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_INSIGHTS_ROLE})- @Operation(operationId = "createDashboard", summary = "Create a dashboard")- Dashboard create(@BeanParam RequestParams requestParams, @Valid Dashboard dashboard);+ @Operation(operationId = "createDashboard", summary = "Create a dashboard",+ description = "Creates a dashboard in an accessible realm. The server assigns the authenticated user as owner and initially stores the dashboard with shared access.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.ServerError+ Dashboard create(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Dashboard definition to create. The server assigns ownerId and initially forces SHARED access.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = Dashboard.class),+ examples = @ExampleObject(name = "Operations dashboard", summary = "Create an empty responsive dashboard", value = DASHBOARD_CREATE))) @Valid Dashboard dashboard);@PUT@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_INSIGHTS_ROLE})- @Operation(operationId = "updateDashboard", summary = "Update a dashboard")- Dashboard update(@BeanParam RequestParams requestParams, @Valid Dashboard dashboard);+ @Operation(operationId = "updateDashboard", summary = "Update a dashboard",+ description = "Updates an existing dashboard when the authenticated user can modify it in the dashboard's realm.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @OpenApiResponses.ServerError+ Dashboard update(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Complete dashboard definition to update, including its id and realm.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = Dashboard.class),+ examples = @ExampleObject(name = "Update operations dashboard", summary = "Rename an existing shared dashboard", value = DASHBOARD_UPDATE))) @Valid Dashboard dashboard);@DELETE@Path("{realm}/{dashboardId}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_INSIGHTS_ROLE})- @Operation(operationId = "deleteDashboard", summary = "Delete a dashboard")- void delete(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("dashboardId") String dashboardId);+ @Operation(operationId = "deleteDashboard", summary = "Delete a dashboard",+ description = "Permanently removes a dashboard when the authenticated user can modify it in the requested realm.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @OpenApiResponses.ServerError+ void delete(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = "Dashboard identifier.", example = "operations-overview") @PathParam("dashboardId") String dashboardId);}diff --git a/model/src/main/java/org/openremote/model/datapoint/AssetDatapointResource.java b/model/src/main/java/org/openremote/model/datapoint/AssetDatapointResource.javaindex d98e919a2..0e4814179 100644--- a/model/src/main/java/org/openremote/model/datapoint/AssetDatapointResource.java+++ b/model/src/main/java/org/openremote/model/datapoint/AssetDatapointResource.java@@ -20,9 +20,21 @@package org.openremote.model.datapoint;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.ExampleObject;+import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.headers.Header;+import io.swagger.v3.oas.annotations.parameters.RequestBody;+import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.Constants;+import org.openremote.model.datapoint.query.AssetDatapointAllQuery;+import org.openremote.model.datapoint.query.AssetDatapointIntervalQuery;+import org.openremote.model.datapoint.query.AssetDatapointLTTBQuery;+import org.openremote.model.datapoint.query.AssetDatapointNearestQuery;import org.openremote.model.datapoint.query.AssetDatapointQuery;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.annotation.security.RolesAllowed;import jakarta.ws.rs.*;@@ -30,8 +42,10 @@ import jakarta.ws.rs.container.AsyncResponse;import jakarta.ws.rs.container.Suspended;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.*;+import static org.openremote.model.http.OpenApiExamples.*;-@Tag(name = "Asset Datapoint", description = "Operations on asset datapoints")+@Tag(name = "Asset Datapoint", description = "Query and export historical values stored for asset attributes")@Path("asset/datapoint")public interface AssetDatapointResource {@@ -46,30 +60,63 @@ public interface AssetDatapointResource {@Path("{assetId}/{attributeName}")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "getDatapoints", summary = "Retrieve the historical datapoints of an asset attribute")+ @Operation(operationId = "getDatapoints", summary = "Retrieve the historical datapoints of an asset attribute",+ description = "Returns stored historical values for one attribute. A null body returns the available series; a polymorphic query body controls the time range and retrieval or aggregation strategy. Anonymous access requires public-read access on both asset and attribute.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ @OpenApiResponses.NotFound+ @OpenApiResponses.PayloadTooLargeValueDatapoint<?>[] getDatapoints(@BeanParam RequestParams requestParams,- @PathParam("assetId") String assetId,- @PathParam("attributeName") String attributeName,- AssetDatapointQuery query);+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId,+ @Parameter(description = ATTRIBUTE_NAME, example = EXAMPLE_ATTRIBUTE_NAME) @PathParam("attributeName") String attributeName,+ @RequestBody(description = "Optional polymorphic datapoint query. Set type to all, interval, lttb, or nearest. Omit the body to return the available stored series.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(+ oneOf = {+ AssetDatapointAllQuery.class,+ AssetDatapointIntervalQuery.class,+ AssetDatapointLTTBQuery.class,+ AssetDatapointNearestQuery.class+ }),+ examples = {+ @ExampleObject(name = "All values", summary = "Return every datapoint in a one-day inclusive range", value = DATAPOINT_ALL_QUERY),+ @ExampleObject(name = "Hourly average", summary = "Average one day of values into hourly buckets and fill gaps", value = DATAPOINT_INTERVAL_QUERY),+ @ExampleObject(name = "LTTB downsampling", summary = "Downsample one day to at most 500 representative points", value = DATAPOINT_LTTB_QUERY),+ @ExampleObject(name = "Nearest value", summary = "Return the closest datapoint at or before a Unix-seconds timestamp", value = DATAPOINT_NEAREST_QUERY)+ })) AssetDatapointQuery query);@GET@Path("periods")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ASSETS_ROLE})- @Operation(operationId = "getDatapointPeriod", summary = "Retrieve a datapoint period of an asset attribute")+ @Operation(operationId = "getDatapointPeriod", summary = "Retrieve a datapoint period of an asset attribute",+ description = "Returns the oldest and newest stored timestamps for one attribute. The asset and attribute must be readable by the authenticated user and configured for datapoint storage.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFoundDatapointPeriod getDatapointPeriod(@BeanParam RequestParams requestParams,- @QueryParam("assetId") String assetId,- @QueryParam("attributeName") String attributeName);+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID, required = true) @QueryParam("assetId") String assetId,+ @Parameter(description = ATTRIBUTE_NAME, example = EXAMPLE_ATTRIBUTE_NAME, required = true) @QueryParam("attributeName") String attributeName);@GET@Path("export")@Produces("application/zip")@RolesAllowed({Constants.READ_ASSETS_ROLE})- @Operation(operationId = "getDatapointExport", summary = "Retrieve a datapoint export of an asset attribute")+ @Operation(operationId = "getDatapointExport", summary = "Export historical datapoints",+ description = "Streams a ZIP archive containing exported datapoints for one or more attribute references over the requested inclusive time range. attributeRefs is a JSON-encoded array of objects with id and name fields.")+ @ApiResponse(responseCode = "200", description = "A ZIP archive containing the exported data",+ headers = @Header(name = "Content-Disposition", description = "Attachment filename for the ZIP archive", schema = @Schema(type = "string", example = "attachment; filename=\"dataexport.zip\"")),+ content = @Content(mediaType = "application/zip", schema = @Schema(type = "string", format = "binary")))+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @OpenApiResponses.PayloadTooLarge+ @OpenApiResponses.ServerErrorvoid getDatapointExport(@Suspended AsyncResponse asyncResponse,- @QueryParam("attributeRefs") String attributeRefsString,- @QueryParam("fromTimestamp") long fromTimestamp,- @QueryParam("toTimestamp") long toTimestamp,- @QueryParam("format") @DefaultValue("CSV") DatapointExportFormat format);+ @Parameter(description = "JSON-encoded array of objects with id and name fields.", example = "[{\"id\":\"7A6p4AnLTkKxJUCQAAABAA\",\"name\":\"temperature\"}]", required = true) @QueryParam("attributeRefs") String attributeRefsString,+ @Parameter(description = "Start of the export range as Unix time in milliseconds.", example = EXAMPLE_TIMESTAMP, required = true) @QueryParam("fromTimestamp") long fromTimestamp,+ @Parameter(description = "End of the export range as Unix time in milliseconds.", example = "1767312000000", required = true) @QueryParam("toTimestamp") long toTimestamp,+ @Parameter(description = "Export file format.", example = "CSV") @QueryParam("format") @DefaultValue("CSV") DatapointExportFormat format);}diff --git a/model/src/main/java/org/openremote/model/datapoint/AssetPredictedDatapointResource.java b/model/src/main/java/org/openremote/model/datapoint/AssetPredictedDatapointResource.javaindex 5395f41ae..87bfd351b 100644--- a/model/src/main/java/org/openremote/model/datapoint/AssetPredictedDatapointResource.java+++ b/model/src/main/java/org/openremote/model/datapoint/AssetPredictedDatapointResource.java@@ -20,14 +20,18 @@package org.openremote.model.datapoint;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.parameters.RequestBody;import io.swagger.v3.oas.annotations.tags.Tag;import jakarta.ws.rs.*;import org.openremote.model.datapoint.query.AssetDatapointQuery;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.*;-@Tag(name = "Asset Predicted Datapoint", description = "Operations on asset predicted datapoints")+@Tag(name = "Asset Predicted Datapoint", description = "Read and replace predicted future values for asset attributes")@Path("asset/predicted")public interface AssetPredictedDatapointResource {/**@@ -41,18 +45,28 @@ public interface AssetPredictedDatapointResource {@Path("{assetId}/{attributeName}")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "getPredictedDatapoints", summary = "Retrieve the predicted datapoints of an asset attribute")+ @Operation(operationId = "getPredictedDatapoints", summary = "Retrieve the predicted datapoints of an asset attribute",+ description = "Queries predicted values for one attribute using the supplied time-range and aggregation criteria. Anonymous access requires public-read access on both asset and attribute.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ @OpenApiResponses.NotFoundValueDatapoint<?>[] getPredictedDatapoints(@BeanParam RequestParams requestParams,- @PathParam("assetId") String assetId,- @PathParam("attributeName") String attributeName,- AssetDatapointQuery query);+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId,+ @Parameter(description = ATTRIBUTE_NAME, example = EXAMPLE_ATTRIBUTE_NAME) @PathParam("attributeName") String attributeName,+ @RequestBody(description = "Optional time range, ordering, limit, and aggregation strategy for predicted values.") AssetDatapointQuery query);@PUT@Path("{assetId}/{attributeName}")@Consumes(APPLICATION_JSON)- @Operation(operationId = "writePredictedDatapoints", summary = "Write the predicted datapoints of an asset attribute")+ @Operation(operationId = "writePredictedDatapoints", summary = "Write the predicted datapoints of an asset attribute",+ description = "Replaces or adds predicted values for one attribute. Anonymous access is allowed only when the asset and attribute are public-write; authenticated callers require attribute-write access.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ @OpenApiResponses.NotFoundvoid writePredictedDatapoints(@BeanParam RequestParams requestParams,- @PathParam("assetId") String assetId,- @PathParam("attributeName") String attributeName,- ValueDatapoint<?>[] predictedDatapoints);+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId,+ @Parameter(description = ATTRIBUTE_NAME, example = EXAMPLE_ATTRIBUTE_NAME) @PathParam("attributeName") String attributeName,+ @RequestBody(required = true, description = "Timestamped predicted values to store for the attribute.") ValueDatapoint<?>[] predictedDatapoints);}diff --git a/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointAllQuery.java b/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointAllQuery.javaindex ceac7c5f7..0be9a85ed 100644--- a/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointAllQuery.java+++ b/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointAllQuery.java@@ -1,5 +1,6 @@package org.openremote.model.datapoint.query;+import io.swagger.v3.oas.annotations.media.Schema;import org.openremote.model.attribute.AttributeRef;import java.time.Instant;@@ -7,6 +8,9 @@ import java.time.LocalDateTime;import java.time.ZoneId;import java.util.HashMap;+@Schema(description = "Returns every stored datapoint in the inclusive range, ordered from newest to oldest. "+ + "Use this when the complete series is needed without aggregation or downsampling. Supports numeric, "+ + "boolean, text, and JSON-compatible complex attribute values.")public class AssetDatapointAllQuery extends AssetDatapointQuery {public AssetDatapointAllQuery() {}diff --git a/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointIntervalQuery.java b/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointIntervalQuery.javaindex 04d885e0c..3cc509727 100644--- a/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointIntervalQuery.java+++ b/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointIntervalQuery.java@@ -1,5 +1,6 @@package org.openremote.model.datapoint.query;+import io.swagger.v3.oas.annotations.media.Schema;import org.openremote.model.attribute.AttributeRef;import org.openremote.model.datapoint.DatapointInterval;@@ -9,10 +10,30 @@ import java.time.ZoneId;import java.util.Arrays;import java.util.HashMap;+@Schema(description = "Aggregates numeric or boolean datapoints from the inclusive range into aligned time "+ + "buckets and returns buckets in chronological order. Use this to summarize a series at a regular "+ + "resolution. Numeric attributes support every formula; boolean attributes support every formula "+ + "except `DIFFERENCE` and are aggregated as 1 for true and 0 for false.")public class AssetDatapointIntervalQuery extends AssetDatapointQuery {+ @Schema(description = "PostgreSQL interval literal that sets the bucket width. Include a positive amount "+ + "and unit, for example `1 hour`, `5 minutes`, or `1 day`.",+ example = "1 hour",+ requiredMode = Schema.RequiredMode.REQUIRED)public String interval;++ @Schema(description = "When true, returns empty buckets across the requested range using time-bucket gap "+ + "filling; their aggregate is generally null. When false, only buckets containing datapoints are "+ + "returned. Defaults to false.",+ example = "true")public boolean gapFill;++ @Schema(description = "Aggregation applied per bucket: `MIN`, `AVG`, and `MAX` calculate the corresponding "+ + "value; `DIFFERENCE` calculates the change between the last values of consecutive buckets; "+ + "`COUNT` counts datapoints; `SUM` totals numeric values (or true values for booleans); `MODE` "+ + "selects the most frequent value; and `MEDIAN` selects the middle value. `DIFFERENCE` is numeric "+ + "only.",+ requiredMode = Schema.RequiredMode.REQUIRED)public Formula formula;public enum Formula {diff --git a/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointLTTBQuery.java b/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointLTTBQuery.javaindex fa7b391e2..e746a1157 100644--- a/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointLTTBQuery.java+++ b/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointLTTBQuery.java@@ -1,5 +1,6 @@package org.openremote.model.datapoint.query;+import io.swagger.v3.oas.annotations.media.Schema;import org.openremote.model.attribute.AttributeRef;import java.time.Instant;@@ -7,8 +8,16 @@ import java.time.LocalDateTime;import java.time.ZoneId;import java.util.HashMap;+@Schema(description = "Downsamples numeric or boolean datapoints from the inclusive range with the "+ + "Largest-Triangle-Three-Buckets (LTTB) algorithm while preserving the series' visual shape. Use this "+ + "to reduce a large series for charts. Results are chronological; boolean values are processed as "+ + "1 for true and 0 for false. Other attribute value types are rejected.")public final class AssetDatapointLTTBQuery extends AssetDatapointQuery {+ @Schema(description = "Requested maximum number of representative datapoints after downsampling. Fewer "+ + "points are returned when the range contains fewer datapoints.",+ example = "500",+ requiredMode = Schema.RequiredMode.REQUIRED)public int amountOfPoints;public AssetDatapointLTTBQuery() {}diff --git a/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointNearestQuery.java b/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointNearestQuery.javaindex d06cc39df..8000dc4b8 100644--- a/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointNearestQuery.java+++ b/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointNearestQuery.java@@ -1,5 +1,6 @@package org.openremote.model.datapoint.query;+import io.swagger.v3.oas.annotations.media.Schema;import org.openremote.model.attribute.AttributeRef;import java.util.HashMap;@@ -9,6 +10,9 @@ import java.util.HashMap;* associated with a specific `AttributeRef` at a specified timestamp. It is designed to find the* closest datapoint that precedes the requested timestamp.*/+@Schema(description = "Returns at most one numeric datapoint: the closest value at or before the requested "+ + "time. Use `fromTimestamp` as a Unix-seconds timestamp at the HTTP API boundary. `toTimestamp`, "+ + "`fromTime`, and `toTime` are ignored. The equality boundary is inclusive.")public class AssetDatapointNearestQuery extends AssetDatapointQuery {public AssetDatapointNearestQuery() {diff --git a/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointQuery.java b/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointQuery.javaindex 6ad9745ca..02d56bbc0 100644--- a/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointQuery.java+++ b/model/src/main/java/org/openremote/model/datapoint/query/AssetDatapointQuery.java@@ -22,6 +22,8 @@ package org.openremote.model.datapoint.query;import com.fasterxml.jackson.annotation.JsonSubTypes;import com.fasterxml.jackson.annotation.JsonTypeInfo;import com.fasterxml.jackson.databind.annotation.JsonDeserialize;+import io.swagger.v3.oas.annotations.media.DiscriminatorMapping;+import io.swagger.v3.oas.annotations.media.Schema;import org.openremote.model.attribute.AttributeRef;import java.io.Serializable;@@ -40,13 +42,45 @@ import java.util.HashMap;property = "type",defaultImpl = AssetDatapointAllQuery.class)+@Schema(+ description = "Polymorphic historical-datapoint query. Select `all` to return every value, "+ + "`interval` to aggregate values into time buckets, `lttb` to downsample a numeric "+ + "or boolean series, or `nearest` to retrieve the last value at or before a time.",+ discriminatorProperty = "type",+ discriminatorMapping = {+ @DiscriminatorMapping(value = "all", schema = AssetDatapointAllQuery.class),+ @DiscriminatorMapping(value = "interval", schema = AssetDatapointIntervalQuery.class),+ @DiscriminatorMapping(value = "lttb", schema = AssetDatapointLTTBQuery.class),+ @DiscriminatorMapping(value = "nearest", schema = AssetDatapointNearestQuery.class)+ }+)public abstract class AssetDatapointQuery implements Serializable {+ @Schema(description = "Inclusive lower range bound as Unix time in milliseconds for `all`, `interval`, "+ + "and `lttb`; ignored when `fromTime` is supplied. For `nearest` this is instead the requested "+ + "time in Unix seconds and is the only time field used.",+ example = "1767225600000")public long fromTimestamp;++ @Schema(description = "Inclusive upper range bound as Unix time in milliseconds for `all`, `interval`, "+ + "and `lttb`; ignored when `toTime` is supplied and not used by `nearest`.",+ example = "1767312000000")public long toTimestamp;+@JsonDeserialize(using = AssetDatapointQueryLocalDateTimeDeserializer.class)+ @Schema(description = "Inclusive lower range bound for `all`, `interval`, and `lttb` as an ISO local or "+ + "offset date-time. A local value is interpreted in the server time zone; an offset value is "+ + "converted to the server time zone. Takes precedence over `fromTimestamp` and is ignored by "+ + "`nearest`.",+ example = "2026-01-01T00:00:00Z")public LocalDateTime fromTime;+@JsonDeserialize(using = AssetDatapointQueryLocalDateTimeDeserializer.class)+ @Schema(description = "Inclusive upper range bound for `all`, `interval`, and `lttb` as an ISO local or "+ + "offset date-time. A local value is interpreted in the server time zone; an offset value is "+ + "converted to the server time zone. Takes precedence over `toTimestamp` and is ignored by "+ + "`nearest`.",+ example = "2026-01-02T00:00:00Z")public LocalDateTime toTime;public String getSQLQuery(String tableName, Class<?> attributeType) throws IllegalStateException {diff --git a/model/src/main/java/org/openremote/model/gateway/GatewayClientResource.java b/model/src/main/java/org/openremote/model/gateway/GatewayClientResource.javaindex 7f1795068..163e34b48 100644--- a/model/src/main/java/org/openremote/model/gateway/GatewayClientResource.java+++ b/model/src/main/java/org/openremote/model/gateway/GatewayClientResource.java@@ -20,9 +20,15 @@package org.openremote.model.gateway;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.enums.Explode;+import io.swagger.v3.oas.annotations.enums.ParameterStyle;+import io.swagger.v3.oas.annotations.parameters.RequestBody;+import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.Constants;import org.openremote.model.asset.agent.ConnectionStatus;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.annotation.security.RolesAllowed;import jakarta.validation.Valid;@@ -31,12 +37,15 @@ import jakarta.ws.rs.*;import java.util.List;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.EXAMPLE_REALM;+import static org.openremote.model.http.OpenApiDescriptions.REALM;/*** Resource for managing the connection to a central manager*/-@Tag(name = "Gateway", description = "Operations on gateways")+@Tag(name = "Gateway", description = "Configure this Manager's connections to central OpenRemote gateway services")@Path("gateway")public interface GatewayClientResource {/**@@ -46,15 +55,23 @@ public interface GatewayClientResource {@Path("connection/{realm}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ADMIN_ROLE})- @Operation(operationId = "getConnection", summary = "Retrieve the gateway connection of a realm")- GatewayConnection getConnection(@BeanParam RequestParams requestParams, @PathParam("realm") String realm);+ @Operation(operationId = "getConnection", summary = "Retrieve the gateway connection of a realm",+ description = "Returns the central-manager connection configured for a realm, or null when none exists. Realm administrators can read their own realm; super users can read any realm.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @ApiResponse(responseCode = "204", description = "No gateway connection is configured for the realm")+ GatewayConnection getConnection(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm);@GET@Path("status/{realm}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ADMIN_ROLE})- @Operation(operationId = "getConnectionStatus", summary = "Retrieve the gateway connection status of a realm")- ConnectionStatus getConnectionStatus(@BeanParam RequestParams requestParams, @PathParam("realm") String realm);+ @Operation(operationId = "getConnectionStatus", summary = "Retrieve the gateway connection status of a realm",+ description = "Returns the live connection state for the requested local realm.")+ @OpenApiResponses.Ok+ ConnectionStatus getConnectionStatus(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm);/*** Get the {@link GatewayConnection}s for all realms, user must be a super user@@ -63,7 +80,10 @@ public interface GatewayClientResource {@Path("connection")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ADMIN_ROLE})- @Operation(operationId = "getConnections", summary = "Retrieve the gateway connections of all realms")+ @Operation(operationId = "getConnections", summary = "Retrieve the gateway connections of all realms",+ description = "Returns every configured central-manager connection. Unlike the single-realm endpoint, this operation is restricted to super users.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequestList<GatewayConnection> getConnections(@BeanParam RequestParams requestParams);/**@@ -73,18 +93,32 @@ public interface GatewayClientResource {@Path("connection/{realm}")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ADMIN_ROLE})- @Operation(operationId = "setConnection", summary = "Update the gateway connection of a realm")- void setConnection(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @Valid GatewayConnection connection);+ @Operation(operationId = "setConnection", summary = "Update the gateway connection of a realm",+ description = "Creates or replaces the connection for the path realm. The server forces the local realm, including realm predicates in attribute filters, to match the path.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ void setConnection(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @RequestBody(required = true, description = "Central-manager connection settings. localRealm and realms in attribute filters are forced to match the path realm.") @Valid GatewayConnection connection);@DELETE@Path("connection/{realm}")@RolesAllowed({Constants.WRITE_ADMIN_ROLE})- @Operation(operationId = "deleteConnection", summary = "Delete the gateway connection of a realm")- void deleteConnection(@BeanParam RequestParams requestParams, @PathParam("realm") String realm);+ @Operation(operationId = "deleteConnection", summary = "Delete the gateway connection of a realm",+ description = "Removes the central-manager connection for one realm. Realm administrators can remove their own connection; super users can remove any connection.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ void deleteConnection(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm);@DELETE@Path("connection")@RolesAllowed({Constants.WRITE_ADMIN_ROLE})- @Operation(operationId = "deleteConnections", summary = "Delete the gateway connections of multiple realms")- void deleteConnections(@BeanParam RequestParams requestParams, @QueryParam("realm") List<String> realms);+ @Operation(operationId = "deleteConnections", summary = "Delete the gateway connections of multiple realms",+ description = "Removes connections for all repeated realm query parameters. Deleting multiple realms is restricted to super users.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ void deleteConnections(@BeanParam RequestParams requestParams,+ @Parameter(description = "Realm names whose gateway connections should be removed. Repeat the query parameter for multiple realms.", example = EXAMPLE_REALM,+ required = true, style = ParameterStyle.FORM, explode = Explode.TRUE) @QueryParam("realm") List<String> realms);}diff --git a/model/src/main/java/org/openremote/model/gateway/GatewayConnection.java b/model/src/main/java/org/openremote/model/gateway/GatewayConnection.javaindex e25ec5539..91de6d024 100644--- a/model/src/main/java/org/openremote/model/gateway/GatewayConnection.java+++ b/model/src/main/java/org/openremote/model/gateway/GatewayConnection.java@@ -20,6 +20,7 @@package org.openremote.model.gateway;import com.fasterxml.jackson.annotation.JsonCreator;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.persistence.Column;import jakarta.persistence.Entity;@@ -37,39 +38,48 @@ import java.util.Map;@Entity@Table(name = "GATEWAY_CONNECTION")+@Schema(description = "Connection from a local realm to a remote OpenRemote gateway, including credentials and synchronization rules.")public class GatewayConnection {@Id@Column(name = "LOCAL_REALM", nullable = false)+ @Schema(description = "Local realm whose assets participate in this gateway connection.", example = "building")protected String localRealm;@NotNull(message = "{GatewayConnection.host.NotNull}")@Size(min = 1, max = 255, message = "{GatewayConnection.host.Size}")@Column(name = "HOST", nullable = false)+ @Schema(description = "Remote gateway hostname without a scheme.", example = "gateway.example.com")protected String host;@Min(value = 1, message = "{GatewayConnection.port.Range}")@Max(value = 65536, message = "{GatewayConnection.port.Range}")@Column(name = "PORT")+ @Schema(description = "Remote HTTPS or HTTP port.", example = "443")protected Integer port;@Column(name = "REALM", nullable = false)+ @Schema(description = "Realm used to authenticate on the remote gateway.", example = "master")protected String realm;@NotNull(message = "{GatewayConnection.clientId.NotNull}")@Size(min = 1, max = 255, message = "{GatewayConnection.clientId.Size}")@Column(name = "CLIENT_ID", nullable = false, length = 36)+ @Schema(description = "Remote identity-provider client identifier.", example = "openremote")protected String clientId;@NotNull(message = "{GatewayConnection.clientSecret.NotNull}")@Size(min = 36, max = 36, message = "{GatewayConnection.clientSecret.Size}")@Column(name = "CLIENT_SECRET", nullable = false, length = 36)+ @Schema(description = "Remote identity-provider client secret.", format = "password")protected String clientSecret;@Column(name = "SECURED")+ @Schema(description = "Use TLS for the remote connection; defaults to true.", example = "true")protected Boolean secured;@Column(name = "DISABLED")+ @Schema(description = "Keep the configuration but prevent connection and synchronization.", example = "false")protected boolean disabled;/**@@ -79,6 +89,7 @@ public class GatewayConnection {*/@Column(name = "ATTRIBUTE_FILTERS")@JdbcTypeCode(SqlTypes.JSON)+ @Schema(description = "Ordered attribute-event filters; the first matching filter is applied.")protected List<GatewayAttributeFilter> attributeFilters;/**@@ -87,6 +98,7 @@ public class GatewayConnection {*/@Column(name = "SYNC_RULES")@JdbcTypeCode(SqlTypes.JSON)+ @Schema(description = "Synchronization rules keyed by asset type; use * as a wildcard.")protected Map<String, GatewayAssetSyncRule> assetSyncRules;/**diff --git a/model/src/main/java/org/openremote/model/gateway/GatewayServiceResource.java b/model/src/main/java/org/openremote/model/gateway/GatewayServiceResource.javaindex 42ea12346..876ae4366 100644--- a/model/src/main/java/org/openremote/model/gateway/GatewayServiceResource.java+++ b/model/src/main/java/org/openremote/model/gateway/GatewayServiceResource.java@@ -1,16 +1,22 @@package org.openremote.model.gateway;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.parameters.RequestBody;+import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import jakarta.annotation.security.RolesAllowed;import jakarta.ws.rs.*;import org.openremote.model.Constants;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.*;-@Tag(name = "Gateway", description = "Operations on gateways")+@Tag(name = "Gateway", description = "Inspect and control TCP tunnels through connected gateway assets")@Path("gateway")public interface GatewayServiceResource {/**@@ -20,8 +26,12 @@ public interface GatewayServiceResource {@Path("tunnel/{realm}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ADMIN_ROLE})- @Operation(operationId = "getAllActiveTunnelInfos", summary = "Retrieve all active gateway tunnel information of a realm")- GatewayTunnelInfo[] getAllActiveTunnelInfos(@BeanParam RequestParams requestParams, @PathParam("realm") String realm);+ @Operation(operationId = "getAllActiveTunnelInfos", summary = "Retrieve all active gateway tunnels in a realm",+ description = "Returns active tunnels for all gateway assets in the requested realm. Restricted users cannot list an entire realm.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ GatewayTunnelInfo[] getAllActiveTunnelInfos(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm);/*** TODO: write docs@@ -29,14 +39,27 @@ public interface GatewayServiceResource {@GET@Path("tunnel/{realm}/{id}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getGatewayActiveTunnelInfos", summary = "Retrieve the active gateway tunnel information of gateway in a realm")- GatewayTunnelInfo[] getGatewayActiveTunnelInfos(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("id") String gatewayId);+ @Operation(operationId = "getGatewayActiveTunnelInfos", summary = "Retrieve the active tunnels of a gateway",+ description = "Returns active tunnels for one gateway asset. Restricted users may query only a linked gateway.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ GatewayTunnelInfo[] getGatewayActiveTunnelInfos(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = "Gateway asset identifier.", example = EXAMPLE_ASSET_ID) @PathParam("id") String gatewayId);@GET@Path("tunnel/{realm}/{id}/{target}/{targetPort}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getActiveTunnelInfo", summary = "Retrieve the gateway tunnel information of tunnel for a gateway in a realm")- GatewayTunnelInfo getActiveTunnelInfo(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("id") String gatewayId, @PathParam("target") String target, @PathParam("targetPort") int targetPort);+ @Operation(operationId = "getActiveTunnelInfo", summary = "Retrieve one active gateway tunnel",+ description = "Returns the tunnel matching realm, gateway, target host, and target port, or null when no active tunnel matches.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @ApiResponse(responseCode = "204", description = "No active tunnel matches the requested endpoint")+ GatewayTunnelInfo getActiveTunnelInfo(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = "Gateway asset identifier.", example = EXAMPLE_ASSET_ID) @PathParam("id") String gatewayId,+ @Parameter(description = "Host or IP address reachable from the gateway.", example = "192.168.1.20") @PathParam("target") String target,+ @Parameter(description = "TCP port on the target host.", example = "22") @PathParam("targetPort") int targetPort);/*** TODO: write docs@@ -45,8 +68,14 @@ public interface GatewayServiceResource {@Path("tunnel")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "startTunnel", summary = "Start a tunnel for a gateway")- GatewayTunnelInfo startTunnel(GatewayTunnelInfo tunnelInfo);+ @Operation(operationId = "startTunnel", summary = "Start a tunnel for a gateway",+ description = "Requests a TCP tunnel through a connected gateway and returns its allocated local endpoint. When realm is omitted, the authenticated realm is used.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @ApiResponse(responseCode = "417", description = "The gateway could not establish the requested tunnel")+ GatewayTunnelInfo startTunnel(+ @RequestBody(required = true, description = "Gateway, realm, target host, and target port for the requested tunnel. Realm defaults to the authenticated realm.") GatewayTunnelInfo tunnelInfo);/*** TODO: write docs@@ -55,6 +84,12 @@ public interface GatewayServiceResource {@Path("tunnel")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "stopTunnel", summary = "Stop a tunnel for a gateway")- void stopTunnel(GatewayTunnelInfo tunnelInfo);+ @Operation(operationId = "stopTunnel", summary = "Stop a tunnel for a gateway",+ description = "Stops the tunnel identified by the supplied gateway, target, and port information. When realm is omitted, the authenticated realm is used.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @OpenApiResponses.ServerError+ void stopTunnel(+ @RequestBody(required = true, description = "Tunnel identity returned by startTunnel, including gateway and allocated endpoint information.") GatewayTunnelInfo tunnelInfo);}diff --git a/model/src/main/java/org/openremote/model/http/OpenApiDescriptions.java b/model/src/main/java/org/openremote/model/http/OpenApiDescriptions.javanew file mode 100644index 000000000..2208eac40--- /dev/null+++ b/model/src/main/java/org/openremote/model/http/OpenApiDescriptions.java@@ -0,0 +1,43 @@+/*+ * Copyright 2026, OpenRemote Inc.+ *+ * See the CONTRIBUTORS.txt file in the distribution for a+ * full listing of individual contributors.+ *+ * This program is free software: you can redistribute it and/or modify+ * it under the terms of the GNU Affero General Public License as+ * published by the Free Software Foundation, either version 3 of the+ * License, or (at your option) any later version.+ *+ * This program is distributed in the hope that it will be useful,+ * but WITHOUT ANY WARRANTY; without even the implied warranty of+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+ * GNU Affero General Public License for more details.+ *+ * You should have received a copy of the GNU Affero General Public License+ * along with this program. If not, see <http://www.gnu.org/licenses/>.+ */+package org.openremote.model.http;++/**+ * Compile-time constants shared by OpenAPI annotations.+ */+public final class OpenApiDescriptions {++ public static final String REALM = "OpenRemote realm name.";+ public static final String ASSET_ID = "Globally unique 22-character asset identifier.";+ public static final String ATTRIBUTE_NAME = "Attribute name as defined by the asset model.";+ public static final String USER_ID = "Identity-provider user identifier.";+ public static final String CLIENT_ID = "Identity-provider client identifier.";+ public static final String TIMESTAMP = "Unix timestamp in milliseconds.";++ public static final String EXAMPLE_REALM = "building";+ public static final String EXAMPLE_ASSET_ID = "7A6p4AnLTkKxJUCQAAABAA";+ public static final String EXAMPLE_ATTRIBUTE_NAME = "temperature";+ public static final String EXAMPLE_USER_ID = "2f1c17e5-72b8-4dbe-9f8d-c49e66f82e10";+ public static final String EXAMPLE_CLIENT_ID = "openremote";+ public static final String EXAMPLE_TIMESTAMP = "1767225600000";++ private OpenApiDescriptions() {+ }+}diff --git a/model/src/main/java/org/openremote/model/http/OpenApiExamples.java b/model/src/main/java/org/openremote/model/http/OpenApiExamples.javanew file mode 100644index 000000000..50e5e5391--- /dev/null+++ b/model/src/main/java/org/openremote/model/http/OpenApiExamples.java@@ -0,0 +1,360 @@+/*+ * Copyright 2026, OpenRemote Inc.+ *+ * See the CONTRIBUTORS.txt file in the distribution for a+ * full listing of individual contributors.+ *+ * This program is free software: you can redistribute it and/or modify+ * it under the terms of the GNU Affero General Public License as+ * published by the Free Software Foundation, either version 3 of the+ * License, or (at your option) any later version.+ *+ * This program is distributed in the hope that it will be useful,+ * but WITHOUT ANY WARRANTY; without even the implied warranty of+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+ * GNU Affero General Public License for more details.+ *+ * You should have received a copy of the GNU Affero General Public License+ * along with this program. If not, see <http://www.gnu.org/licenses/>.+ */+package org.openremote.model.http;++/**+ * Reusable JSON examples for common OpenAPI request bodies.+ */+public final class OpenApiExamples {++ public static final String ASSET_CREATE = """+ {+ "type": "ThingAsset",+ "name": "Boiler room sensor",+ "realm": "building",+ "attributes": {+ "temperature": {+ "name": "temperature",+ "type": "number",+ "value": 21.5+ },+ "humidity": {+ "name": "humidity",+ "type": "number",+ "value": 48+ }+ }+ }+ """;++ public static final String ASSET_UPDATE = """+ {+ "id": "7A6p4AnLTkKxJUCQAAABAA",+ "version": 3,+ "type": "ThingAsset",+ "name": "Boiler room sensor",+ "realm": "building",+ "accessPublicRead": false,+ "attributes": {+ "temperature": {+ "name": "temperature",+ "type": "number",+ "value": 22.1+ },+ "humidity": {+ "name": "humidity",+ "type": "number",+ "value": 48+ }+ }+ }+ """;++ public static final String ASSET_QUERY = """+ {+ "realm": {+ "name": "building"+ },+ "types": [+ "ThingAsset"+ ],+ "names": [+ {+ "match": "CONTAINS",+ "caseSensitive": false,+ "value": "sensor"+ }+ ],+ "select": {+ "attributes": [+ "temperature",+ "humidity"+ ]+ },+ "orderBy": {+ "property": "NAME",+ "descending": false+ },+ "limit": 100,+ "offset": 0+ }+ """;++ public static final String ATTRIBUTE_VALUE = "21.5";++ public static final String ATTRIBUTE_STATES = """+ [+ {+ "ref": {+ "id": "7A6p4AnLTkKxJUCQAAABAA",+ "name": "temperature"+ },+ "value": 21.5+ },+ {+ "ref": {+ "id": "7A6p4AnLTkKxJUCQAAABAA",+ "name": "humidity"+ },+ "value": 48+ }+ ]+ """;++ public static final String DATAPOINT_ALL_QUERY = """+ {+ "type": "all",+ "fromTime": "2026-01-01T00:00:00Z",+ "toTime": "2026-01-02T00:00:00Z"+ }+ """;++ public static final String DATAPOINT_INTERVAL_QUERY = """+ {+ "type": "interval",+ "fromTimestamp": 1767225600000,+ "toTimestamp": 1767312000000,+ "interval": "1 hour",+ "formula": "AVG",+ "gapFill": true+ }+ """;++ public static final String DATAPOINT_LTTB_QUERY = """+ {+ "type": "lttb",+ "fromTimestamp": 1767225600000,+ "toTimestamp": 1767312000000,+ "amountOfPoints": 500+ }+ """;++ public static final String DATAPOINT_NEAREST_QUERY = """+ {+ "type": "nearest",+ "fromTimestamp": 1767312000+ }+ """;++ public static final String USER_QUERY = """+ {+ "realmPredicate": {+ "name": "building"+ },+ "usernames": [+ {+ "match": "CONTAINS",+ "caseSensitive": false,+ "value": "alex"+ }+ ],+ "serviceUsers": false,+ "select": {+ "basic": true+ },+ "orderBy": {+ "property": "USERNAME",+ "descending": false+ },+ "limit": 100,+ "offset": 0+ }+ """;++ public static final String USER_CREATE = """+ {+ "username": "alex",+ "firstName": "Alex",+ "lastName": "Morgan",+ "email": "[email protected]",+ "enabled": true,+ "attributes": {+ "locale": [+ "en"+ ]+ }+ }+ """;++ public static final String ALARM_CREATE = """+ {+ "title": "Temperature threshold exceeded",+ "content": "Boiler room temperature reached 42 °C.",+ "severity": "HIGH",+ "status": "OPEN",+ "realm": "building"+ }+ """;++ public static final String ALARM_ASSET_LINK_SINGLE = """+ [+ {+ "id": {+ "realm": "building",+ "alarmId": 1234,+ "assetId": "7A6p4AnLTkKxJUCQAAABAA"+ }+ }+ ]+ """;++ public static final String ALARM_ASSET_LINK_MULTIPLE = """+ [+ {+ "id": {+ "realm": "building",+ "alarmId": 1234,+ "assetId": "7A6p4AnLTkKxJUCQAAABAA"+ }+ },+ {+ "id": {+ "realm": "building",+ "alarmId": 1234,+ "assetId": "2Qjr4AnLTkKxJUCQAAACAA"+ }+ }+ ]+ """;++ public static final String ALARM_ASSET_LINK_INVALID_MULTIPLE_ALARMS = """+ [+ {+ "id": {+ "realm": "building",+ "alarmId": 1234,+ "assetId": "7A6p4AnLTkKxJUCQAAABAA"+ }+ },+ {+ "id": {+ "realm": "building",+ "alarmId": 5678,+ "assetId": "2Qjr4AnLTkKxJUCQAAACAA"+ }+ }+ ]+ """;++ public static final String PUSH_NOTIFICATION = """+ {+ "name": "High temperature alert",+ "message": {+ "type": "push",+ "title": "Temperature alert",+ "body": "Boiler room temperature reached 42 °C.",+ "priority": "HIGH",+ "data": {+ "assetId": "7A6p4AnLTkKxJUCQAAABAA"+ }+ },+ "targets": [+ {+ "type": "USER",+ "id": "2f1c17e5-72b8-4dbe-9f8d-c49e66f82e10",+ "locale": "en"+ }+ ]+ }+ """;++ public static final String DASHBOARD_QUERY = """+ {+ "realm": {+ "name": "building"+ },+ "names": [+ {+ "match": "CONTAINS",+ "caseSensitive": false,+ "value": "operations"+ }+ ],+ "conditions": {+ "dashboard": {+ "access": [+ "PUBLIC",+ "SHARED"+ ]+ }+ },+ "start": 0,+ "limit": 50+ }+ """;++ public static final String DASHBOARD_CREATE = """+ {+ "realm": "building",+ "displayName": "Operations overview",+ "template": {+ "columns": 12,+ "refreshInterval": "FIVE_MIN",+ "screenPresets": [+ {+ "id": "desktop",+ "displayName": "Desktop",+ "breakpoint": 1024,+ "scalingPreset": "KEEP_LAYOUT"+ }+ ],+ "widgets": []+ }+ }+ """;++ public static final String DASHBOARD_UPDATE = """+ {+ "id": "operations-overview",+ "version": 2,+ "realm": "building",+ "ownerId": "2f1c17e5-72b8-4dbe-9f8d-c49e66f82e10",+ "access": "SHARED",+ "displayName": "Building operations overview",+ "template": {+ "columns": 12,+ "refreshInterval": "FIVE_MIN",+ "screenPresets": [+ {+ "id": "desktop",+ "displayName": "Desktop",+ "breakpoint": 1024,+ "scalingPreset": "KEEP_LAYOUT"+ }+ ],+ "widgets": []+ }+ }+ """;++ public static final String ASSET_RULESET_CREATE = """+ {+ "assetId": "7A6p4AnLTkKxJUCQAAABAA",+ "name": "High temperature alert",+ "lang": "JSON",+ "enabled": true,+ "accessPublicRead": false,+ "rules": "{\\"rules\\":[{\\"name\\":\\"High temperature alert\\",\\"when\\":{\\"operator\\":\\"OR\\",\\"groups\\":[{\\"operator\\":\\"AND\\",\\"items\\":[{\\"assets\\":{\\"ids\\":[\\"7A6p4AnLTkKxJUCQAAABAA\\"],\\"attributes\\":{\\"items\\":[{\\"name\\":{\\"predicateType\\":\\"string\\",\\"match\\":\\"EXACT\\",\\"value\\":\\"temperature\\"},\\"value\\":{\\"predicateType\\":\\"number\\",\\"operator\\":\\"GREATER_THAN\\",\\"value\\":40}}]}}}]}]},\\"then\\":[{\\"action\\":\\"alarm\\",\\"alarm\\":{\\"title\\":\\"High temperature\\",\\"content\\":\\"%TRIGGER_ASSETS%\\",\\"severity\\":\\"HIGH\\",\\"status\\":\\"OPEN\\"}}]}]}"+ }+ """;++ private OpenApiExamples() {+ }+}diff --git a/model/src/main/java/org/openremote/model/http/OpenApiResponses.java b/model/src/main/java/org/openremote/model/http/OpenApiResponses.javanew file mode 100644index 000000000..c9845f421--- /dev/null+++ b/model/src/main/java/org/openremote/model/http/OpenApiResponses.java@@ -0,0 +1,119 @@+/*+ * Copyright 2026, OpenRemote Inc.+ *+ * See the CONTRIBUTORS.txt file in the distribution for a+ * full listing of individual contributors.+ *+ * This program is free software: you can redistribute it and/or modify+ * it under the terms of the GNU Affero General Public License as+ * published by the Free Software Foundation, either version 3 of the+ * License, or (at your option) any later version.+ *+ * This program is distributed in the hope that it will be useful,+ * but WITHOUT ANY WARRANTY; without even the implied warranty of+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+ * GNU Affero General Public License for more details.+ *+ * You should have received a copy of the GNU Affero General Public License+ * along with this program. If not, see <http://www.gnu.org/licenses/>.+ */+package org.openremote.model.http;++import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.responses.ApiResponse;+import io.swagger.v3.oas.annotations.security.SecurityRequirement;++import java.lang.annotation.Documented;+import java.lang.annotation.Retention;+import java.lang.annotation.Target;++import static java.lang.annotation.ElementType.METHOD;+import static java.lang.annotation.ElementType.TYPE;+import static java.lang.annotation.RetentionPolicy.RUNTIME;++/**+ * Reusable OpenAPI response annotations for the Manager REST API.+ *+ * <p>Swagger Core resolves annotations which are meta-annotated with {@link ApiResponse}. Keeping the standard+ * responses here gives every resource the same wording while still producing ordinary response objects in the+ * generated OpenAPI document.</p>+ */+public final class OpenApiResponses {++ private OpenApiResponses() {+ }++ @Documented+ @Target({METHOD, TYPE})+ @Retention(RUNTIME)+ @ApiResponse(responseCode = "200", description = "The request completed successfully", useReturnTypeSchema = true)+ public @interface Ok {+ }++ @Documented+ @Target({METHOD, TYPE})+ @Retention(RUNTIME)+ @ApiResponse(responseCode = "204", description = "The request completed successfully; no response body is returned")+ public @interface NoContent {+ }++ @Documented+ @Target({METHOD, TYPE})+ @Retention(RUNTIME)+ @ApiResponse(responseCode = "400", description = "The request parameters or body are invalid",+ content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class)))+ public @interface BadRequest {+ }++ @Documented+ @Target({METHOD, TYPE})+ @Retention(RUNTIME)+ @SecurityRequirement(name = "openid")+ @ApiResponse(responseCode = "401", description = "Authentication is required or the supplied credentials are invalid",+ content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class)))+ @ApiResponse(responseCode = "403", description = "The authenticated user does not have permission to perform this operation",+ content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class)))+ public @interface Authenticated {+ }++ @Documented+ @Target({METHOD, TYPE})+ @Retention(RUNTIME)+ @ApiResponse(responseCode = "403", description = "The caller does not have permission to access the requested resource",+ content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class)))+ public @interface Forbidden {+ }++ @Documented+ @Target({METHOD, TYPE})+ @Retention(RUNTIME)+ @ApiResponse(responseCode = "404", description = "The requested resource does not exist",+ content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class)))+ public @interface NotFound {+ }++ @Documented+ @Target({METHOD, TYPE})+ @Retention(RUNTIME)+ @ApiResponse(responseCode = "409", description = "The request conflicts with the current state of the resource",+ content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class)))+ public @interface Conflict {+ }++ @Documented+ @Target({METHOD, TYPE})+ @Retention(RUNTIME)+ @ApiResponse(responseCode = "413", description = "The request or generated response exceeds the configured size limit",+ content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class)))+ public @interface PayloadTooLarge {+ }++ @Documented+ @Target({METHOD, TYPE})+ @Retention(RUNTIME)+ @ApiResponse(responseCode = "500", description = "The operation failed because of an unexpected server error",+ content = @Content(mediaType = "text/plain", schema = @Schema(implementation = String.class)))+ public @interface ServerError {+ }+}diff --git a/model/src/main/java/org/openremote/model/http/RequestParams.java b/model/src/main/java/org/openremote/model/http/RequestParams.javaindex 27eefda04..f3578d471 100644--- a/model/src/main/java/org/openremote/model/http/RequestParams.java+++ b/model/src/main/java/org/openremote/model/http/RequestParams.java@@ -19,6 +19,7 @@*/package org.openremote.model.http;+import io.swagger.v3.oas.annotations.Parameter;import jakarta.validation.constraints.NotNull;import jakarta.ws.rs.HeaderParam;import jakarta.ws.rs.core.Context;@@ -37,12 +38,15 @@ public class RequestParams {public HttpHeaders headers;@HeaderParam(HttpHeaders.AUTHORIZATION)+ @Parameter(hidden = true)public String authorization;@HeaderParam("X-Forwarded-Proto")+ @Parameter(hidden = true)public String forwardedProtoHeader;@HeaderParam("X-Forwarded-Host")+ @Parameter(hidden = true)public String forwardedHostHeader;@Contextdiff --git a/model/src/main/java/org/openremote/model/manager/ConfigurationResource.java b/model/src/main/java/org/openremote/model/manager/ConfigurationResource.javaindex fb19b65b9..708dffcf8 100644--- a/model/src/main/java/org/openremote/model/manager/ConfigurationResource.java+++ b/model/src/main/java/org/openremote/model/manager/ConfigurationResource.java@@ -19,11 +19,16 @@*/package org.openremote.model.manager;-import com.fasterxml.jackson.databind.node.ObjectNode;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;+import io.swagger.v3.oas.annotations.parameters.RequestBody;import org.openremote.model.Constants;import org.openremote.model.file.FileInfo;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.annotation.security.RolesAllowed;@@ -31,7 +36,7 @@ import jakarta.ws.rs.*;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;-@Tag(name = "Configuration", description = "Operations on configurations")+@Tag(name = "Configuration", description = "Read public Manager UI configuration and administer its configuration and images")@Path("configuration")public interface ConfigurationResource {@@ -40,30 +45,48 @@ public interface ConfigurationResource {@Produces(APPLICATION_JSON)@Path("manager")@RolesAllowed({Constants.WRITE_ADMIN_ROLE})- @Operation(operationId = "updateConfiguration", summary = "Update manager configuration")- ManagerAppConfig update(@BeanParam RequestParams requestParams, ManagerAppConfig managerConfiguration);+ @Operation(operationId = "updateConfiguration", summary = "Update manager configuration",+ description = "Replaces manager_config.json and returns the stored configuration. This administrative change affects Manager UI branding and behavior.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.ServerError+ ManagerAppConfig update(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Complete public Manager UI configuration to persist as manager_config.json.") ManagerAppConfig managerConfiguration);@POST@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@Path("manager/file")@RolesAllowed({Constants.WRITE_ADMIN_ROLE})- @Operation(operationId = "fileUpload", summary = "Upload a file")+ @Operation(operationId = "fileUpload", summary = "Upload a Manager configuration image",+ description = "Decodes and stores the supplied FileInfo under the requested relative path, then returns its Manager API path.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.ServerErrorString fileUpload(@BeanParam RequestParams requestParams,- @QueryParam("path")- String path,- FileInfo fileInfo+ @Parameter(description = "Relative storage path and filename for the image.", example = "images/logo.svg", required = true) @QueryParam("path") String path,+ @RequestBody(required = true, description = "File metadata and Base64 or text contents to store.") FileInfo fileInfo);@GET@Produces(APPLICATION_JSON)@Path("manager")- @Operation(operationId = "getManagerConfig", summary = "Retrieve the manager configuration JSON")+ @Operation(operationId = "getManagerConfig", summary = "Retrieve the manager configuration JSON",+ description = "Returns the public Manager application configuration used by clients before and after authentication.")+ @OpenApiResponses.OkManagerAppConfig getManagerConfig();@GET@Path("manager/image/{filename: .+}")- @Operation(operationId = "getManagerConfigImage", summary = "Retrieve manager configuration images")- Object getManagerConfigImage(@PathParam("filename")String fileName);+ @Operation(operationId = "getManagerConfigImage", summary = "Retrieve a Manager configuration image",+ description = "Streams a previously uploaded configuration image using its detected media type.")+ @ApiResponse(responseCode = "200", description = "The image file",+ content = @Content(mediaType = "application/octet-stream", schema = @Schema(type = "string", format = "binary")))+ @OpenApiResponses.NotFound+ @OpenApiResponses.ServerError+ Object getManagerConfigImage(+ @Parameter(description = "Relative image path below the Manager configuration image directory.", example = "images/logo.svg") @PathParam("filename") String fileName);}diff --git a/model/src/main/java/org/openremote/model/map/MapResource.java b/model/src/main/java/org/openremote/model/map/MapResource.javaindex 74651de38..050f319c9 100644--- a/model/src/main/java/org/openremote/model/map/MapResource.java+++ b/model/src/main/java/org/openremote/model/map/MapResource.java@@ -21,9 +21,16 @@ package org.openremote.model.map;import com.fasterxml.jackson.databind.node.ObjectNode;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.headers.Header;+import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.parameters.RequestBody;+import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.Constants;import jakarta.ws.rs.core.Response;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import org.openremote.model.manager.MapConfig;@@ -31,7 +38,7 @@ import jakarta.annotation.security.RolesAllowed;import jakarta.ws.rs.*;import jakarta.ws.rs.core.MediaType;-@Tag(name = "Map", description = "Operations on maps")+@Tag(name = "Map", description = "Configure the Manager map and serve map styles, vector tiles, and custom MBTiles data")@Path("map")public interface MapResource {@@ -42,8 +49,13 @@ public interface MapResource {@Consumes(MediaType.APPLICATION_JSON)@Produces(MediaType.APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ADMIN_ROLE})- @Operation(operationId = "saveSettings", summary = "Update map settings")- ObjectNode saveSettings(@BeanParam RequestParams requestParams, MapConfig mapConfig);+ @Operation(operationId = "saveSettings", summary = "Update map settings",+ description = "Stores the map configuration and returns the resulting public MapLibre settings.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ ObjectNode saveSettings(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Map provider, style, bounds, and custom-map settings to persist.") MapConfig mapConfig);/*** Returns style used to initialise MapLibre GL@@ -51,7 +63,9 @@ public interface MapResource {*/@GET@Produces(MediaType.APPLICATION_JSON)- @Operation(operationId = "getSettings", summary = "Retrieve the style used for MapLibre GL")+ @Operation(operationId = "getSettings", summary = "Retrieve the style used for MapLibre GL",+ description = "Returns realm-aware public MapLibre settings with externally reachable URLs derived from proxy headers.")+ @OpenApiResponses.OkObjectNode getSettings(@BeanParam RequestParams requestParams);/**@@ -60,8 +74,17 @@ public interface MapResource {@GET@Produces("application/vnd.mapbox-vector-tile")@Path("tile/{zoom}/{column}/{row}")- @Operation(operationId = "getTile", summary = "Retrieve the vector tile data for Mapbox GL")- Response getTile(@PathParam("zoom")int zoom, @PathParam("column")int column, @PathParam("row")int row);+ @Operation(operationId = "getTile", summary = "Retrieve vector tile data for MapLibre GL",+ description = "Returns a pre-compressed Mapbox vector tile for the requested zoom, column, and row coordinates.")+ @ApiResponse(responseCode = "200", description = "Gzip-compressed vector tile",+ headers = @Header(name = "Content-Encoding", description = "Indicates that the tile bytes are already compressed", schema = @Schema(type = "string", allowableValues = "gzip")),+ content = @Content(mediaType = "application/vnd.mapbox-vector-tile", schema = @Schema(type = "string", format = "binary")))+ @ApiResponse(responseCode = "204", description = "No tile exists at the requested coordinates")+ @OpenApiResponses.BadRequest+ Response getTile(+ @Parameter(description = "Web Mercator zoom level.", example = "14") @PathParam("zoom") int zoom,+ @Parameter(description = "Web Mercator tile X coordinate.", example = "8392") @PathParam("column") int column,+ @Parameter(description = "Web Mercator tile Y coordinate.", example = "5469") @PathParam("row") int row);/*** Saves mbtiles file@@ -71,8 +94,17 @@ public interface MapResource {@Consumes(MediaType.APPLICATION_OCTET_STREAM)@Produces(MediaType.APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ADMIN_ROLE})- @Operation(operationId = "uploadMap", summary = "Saves mbtiles file")- ObjectNode uploadMap(@BeanParam RequestParams requestParams, @QueryParam("filename") String filename);+ @Operation(operationId = "uploadMap", summary = "Upload a custom MBTiles map",+ description = "Stores the raw request body as the realm's custom MBTiles database and returns the resulting public map settings.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.PayloadTooLarge+ @OpenApiResponses.ServerError+ @RequestBody(required = true, description = "Raw MBTiles SQLite database bytes.",+ content = @Content(mediaType = MediaType.APPLICATION_OCTET_STREAM, schema = @Schema(type = "string", format = "binary")))+ ObjectNode uploadMap(@BeanParam RequestParams requestParams,+ @Parameter(description = "Original MBTiles filename used for validation and storage.", example = "building.mbtiles", required = true) @QueryParam("filename") String filename);/*** Retrieve if the map is custom and custom map limit@@ -81,7 +113,11 @@ public interface MapResource {@Path("getCustomMapInfo")@Produces(MediaType.APPLICATION_JSON)@RolesAllowed({Constants.READ_ADMIN_ROLE})- @Operation(operationId = "getCustomMapInfo", summary = "Retrieve if the map is custom and custom map limit")+ @Operation(operationId = "getCustomMapInfo", summary = "Retrieve custom-map status and upload limit",+ description = "Reports whether custom MBTiles data is installed and the maximum accepted upload size.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.ServerErrorObjectNode getCustomMapInfo();/**@@ -91,6 +127,10 @@ public interface MapResource {@Path("deleteMap")@Produces(MediaType.APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ADMIN_ROLE})- @Operation(operationId = "deleteMap", summary = "Removes mbtiles file")+ @Operation(operationId = "deleteMap", summary = "Remove the custom MBTiles map",+ description = "Deletes the installed custom MBTiles database and returns the fallback public map settings.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequestObjectNode deleteMap(@BeanParam RequestParams requestParams);}diff --git a/model/src/main/java/org/openremote/model/notification/Notification.java b/model/src/main/java/org/openremote/model/notification/Notification.javaindex 56c9a156f..cce60df63 100644--- a/model/src/main/java/org/openremote/model/notification/Notification.java+++ b/model/src/main/java/org/openremote/model/notification/Notification.java@@ -21,9 +21,11 @@ package org.openremote.model.notification;import com.fasterxml.jackson.annotation.JsonCreator;import com.fasterxml.jackson.annotation.JsonProperty;+import io.swagger.v3.oas.annotations.media.Schema;import java.util.*;+@Schema(description = "Notification submission containing a typed message, one or more targets, and optional repeat scheduling.")public class Notification {public enum Source {@@ -41,6 +43,7 @@ public class Notification {CUSTOM}+ @Schema(description = "Delivery target. The target type determines whether id refers to a user, asset, realm, or custom address.")public static class Target {protected TargetType type;@@ -125,10 +128,15 @@ public class Notification {public static final String HEADER_SOURCE = Notification.class.getName() + ".SOURCE";public static final String HEADER_SOURCE_ID = Notification.class.getName() + ".SOURCEID";+ @Schema(description = "Optional human-readable notification name used in delivery records.", example = "High temperature alert")protected String name;+ @Schema(description = "Typed notification message; its discriminator selects email, push, or another installed message subtype.")protected AbstractNotificationMessage message;+ @Schema(description = "Optional repeat cadence for scheduled delivery.")protected RepeatFrequency repeatFrequency;+ @Schema(description = "Repeat interval expression interpreted with repeatFrequency.")protected String repeatInterval;+ @Schema(description = "One or more recipients. Authorization is checked for the complete set before anything is queued.")protected List<Target> targets;public Notification() {diff --git a/model/src/main/java/org/openremote/model/notification/NotificationResource.java b/model/src/main/java/org/openremote/model/notification/NotificationResource.javaindex 6210c664c..06f24d8eb 100644--- a/model/src/main/java/org/openremote/model/notification/NotificationResource.java+++ b/model/src/main/java/org/openremote/model/notification/NotificationResource.java@@ -21,15 +21,23 @@ package org.openremote.model.notification;import com.fasterxml.jackson.databind.JsonNode;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.ExampleObject;+import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.parameters.RequestBody;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.Constants;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.annotation.security.RolesAllowed;import jakarta.ws.rs.*;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.*;+import static org.openremote.model.http.OpenApiExamples.PUSH_NOTIFICATION;-@Tag(name = "Notification", description = "Operations on notifications")+@Tag(name = "Notification", description = "Send notifications and query, delete, deliver, or acknowledge their delivery records")@Path("notification")public interface NotificationResource {@@ -42,20 +50,24 @@ public interface NotificationResource {@GET@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_NOTIFICATIONS_ROLE})- @Operation(operationId = "getNotifications", summary = "Retrieve sent notifications matching the supplied criteria")+ @Operation(operationId = "getNotifications", summary = "Retrieve sent notifications matching filter criteria",+ description = "Returns sent-notification records filtered by identity, message type, time, realm, target, source, sorting, and pagination. Results are realm-scoped and sensitive target/source identifiers are redacted when the caller lacks user or asset read permission.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequestSentNotification[] getNotifications(@BeanParam RequestParams requestParams,- @QueryParam("id") Long id,- @QueryParam("type") String type,- @QueryParam("from") Long fromTimestamp,- @QueryParam("to") Long toTimestamp,- @QueryParam("realmId") String realmId,- @QueryParam("userId") String userId,- @QueryParam("assetId") String assetId,- @QueryParam("source") Notification.Source source,- @QueryParam("sort") SentNotification.SortField sort,- @QueryParam("descending") Boolean descending,- @QueryParam("offset") Integer offset,- @QueryParam("limit") Integer limit);+ @Parameter(description = "Return only this sent-notification record.", example = "42") @QueryParam("id") Long id,+ @Parameter(description = "Notification message type discriminator.", example = "push") @QueryParam("type") String type,+ @Parameter(description = "Inclusive lower bound for the sent timestamp, in Unix milliseconds.", example = EXAMPLE_TIMESTAMP) @QueryParam("from") Long fromTimestamp,+ @Parameter(description = "Exclusive upper bound for the sent timestamp, in Unix milliseconds.", example = "1767312000000") @QueryParam("to") Long toTimestamp,+ @Parameter(description = "Return notifications associated with this realm.", example = EXAMPLE_REALM) @QueryParam("realmId") String realmId,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @QueryParam("userId") String userId,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @QueryParam("assetId") String assetId,+ @Parameter(description = "Origin that created the notification.") @QueryParam("source") Notification.Source source,+ @Parameter(description = "Field used to order the result set.") @QueryParam("sort") SentNotification.SortField sort,+ @Parameter(description = "Reverse the selected sort order.", example = "true") @QueryParam("descending") Boolean descending,+ @Parameter(description = "Number of matching records to skip.", example = "0") @QueryParam("offset") Integer offset,+ @Parameter(description = "Maximum number of records to return.", example = "100") @QueryParam("limit") Integer limit);/*** Removes all sent notifications that have been sent to the specified targets; optionally limiting the scope of the@@ -65,15 +77,19 @@ public interface NotificationResource {*/@DELETE@RolesAllowed({Constants.WRITE_NOTIFICATIONS_ROLE})- @Operation(operationId = "removeNotifications", summary = "Delete all sent notifications by targets")+ @Operation(operationId = "removeNotifications", summary = "Delete sent notifications matching filter criteria",+ description = "Permanently removes all records matching the optional ID, type, time, realm, user, and asset filters. This bulk operation is restricted to a super user.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequestvoid removeNotifications(@BeanParam RequestParams requestParams,- @QueryParam("id") Long id,- @QueryParam("type") String type,- @QueryParam("from") Long fromTimestamp,- @QueryParam("to") Long toTimestamp,- @QueryParam("realmId") String realmId,- @QueryParam("userId") String userId,- @QueryParam("assetId") String assetId);+ @Parameter(description = "Delete only this sent-notification record.", example = "42") @QueryParam("id") Long id,+ @Parameter(description = "Delete records with this notification message type.", example = "push") @QueryParam("type") String type,+ @Parameter(description = "Inclusive lower bound for the sent timestamp, in Unix milliseconds.", example = EXAMPLE_TIMESTAMP) @QueryParam("from") Long fromTimestamp,+ @Parameter(description = "Exclusive upper bound for the sent timestamp, in Unix milliseconds.", example = "1767312000000") @QueryParam("to") Long toTimestamp,+ @Parameter(description = "Delete records associated with this realm.", example = EXAMPLE_REALM) @QueryParam("realmId") String realmId,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @QueryParam("userId") String userId,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @QueryParam("assetId") String assetId);/*** Remove a specific sent notification by ID.@@ -81,9 +97,13 @@ public interface NotificationResource {@DELETE@Path("{notificationId}")@RolesAllowed({Constants.WRITE_NOTIFICATIONS_ROLE})- @Operation(operationId = "removeNotification", summary = "Delete a sent notification")+ @Operation(operationId = "removeNotification", summary = "Delete a sent notification",+ description = "Permanently removes one sent-notification record. This operation is restricted to a super user and is idempotent when the ID does not exist.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequestvoid removeNotification(@BeanParam RequestParams requestParams,- @PathParam("notificationId") Long notificationId);+ @Parameter(description = "Numeric sent-notification identifier.", example = "42") @PathParam("notificationId") Long notificationId);/*** Send a notification to one or more targets; the authorisation of the requesting user will determine whether or@@ -94,9 +114,15 @@ public interface NotificationResource {@Path("alert")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_NOTIFICATIONS_ROLE})- @Operation(operationId = "sendNotification", summary = "Send a notification to one or more targets")+ @Operation(operationId = "sendNotification", summary = "Send a notification to one or more targets",+ description = "Queues a notification for delivery. Authorization is checked for every target; if any target is inaccessible, the complete request fails rather than sending a partial set.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequestvoid sendNotification(@BeanParam RequestParams requestParams,- Notification notification);+ @RequestBody(required = true, description = "Message, source, and one or more delivery targets to queue.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = Notification.class),+ examples = @ExampleObject(name = "Push notification", summary = "Send a high-priority asset alert to one user", value = PUSH_NOTIFICATION))) Notification notification);/*** Allows a target to mark a notification as delivered.@@ -106,10 +132,15 @@ public interface NotificationResource {*/@PUT@Path("{notificationId}/delivered")- @Operation(operationId = "notificationDelivered", summary = "Update a notification as delivered")+ @Operation(operationId = "notificationDelivered", summary = "Mark a notification as delivered",+ description = "Marks one target's notification as delivered after matching both notificationId and targetId. Anonymous callers may update notifications sent to a public asset; authenticated callers are constrained to their own user, realm, or accessible assets.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ @OpenApiResponses.NotFoundvoid notificationDelivered(@BeanParam RequestParams requestParams,- @QueryParam("targetId") String targetId,- @PathParam("notificationId") Long notificationId);+ @Parameter(description = "User, asset, or realm target identifier whose delivery state is updated.", example = EXAMPLE_USER_ID, required = true) @QueryParam("targetId") String targetId,+ @Parameter(description = "Numeric sent-notification identifier.", example = "42") @PathParam("notificationId") Long notificationId);/*** Allows a target to acknowledge a notification with an optional acknowledgement value.@@ -120,11 +151,17 @@ public interface NotificationResource {@PUT@Path("{notificationId}/acknowledged")@Consumes(APPLICATION_JSON)- @Operation(operationId = "notificationAcknowledged", summary = "Update a notification as acknowledged")+ @Operation(operationId = "notificationAcknowledged", summary = "Acknowledge a notification",+ description = "Marks one target's notification as acknowledged and stores the optional JSON acknowledgement value. Access rules are identical to notificationDelivered.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ @OpenApiResponses.NotFoundvoid notificationAcknowledged(@BeanParam RequestParams requestParams,- @QueryParam("targetId") String targetId,- @PathParam("notificationId") Long notificationId,- JsonNode acknowledgement);+ @Parameter(description = "User, asset, or realm target identifier whose acknowledgement state is updated.", example = EXAMPLE_USER_ID, required = true) @QueryParam("targetId") String targetId,+ @Parameter(description = "Numeric sent-notification identifier.", example = "42") @PathParam("notificationId") Long notificationId,+ @RequestBody(description = "Optional arbitrary JSON acknowledgement value.",+ content = @Content(schema = @Schema(nullable = true))) JsonNode acknowledgement);/*** Counts sent notifications matching the supplied criteria; uses the same scoping and access rules as@@ -134,13 +171,17 @@ public interface NotificationResource {@Path("count")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_NOTIFICATIONS_ROLE})- @Operation(operationId = "getNotificationsCount", summary = "Count sent notifications matching the supplied criteria")+ @Operation(operationId = "getNotificationsCount", summary = "Count sent notifications matching filter criteria",+ description = "Returns the count for the same realm-scoped type, time, target, and source filters supported by getNotifications without loading notification records.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequestlong getNotificationsCount(@BeanParam RequestParams requestParams,- @QueryParam("type") String type,- @QueryParam("from") Long fromTimestamp,- @QueryParam("to") Long toTimestamp,- @QueryParam("realmId") String realmId,- @QueryParam("userId") String userId,- @QueryParam("assetId") String assetId,- @QueryParam("source") Notification.Source source);+ @Parameter(description = "Notification message type discriminator.", example = "push") @QueryParam("type") String type,+ @Parameter(description = "Inclusive lower bound for the sent timestamp, in Unix milliseconds.", example = EXAMPLE_TIMESTAMP) @QueryParam("from") Long fromTimestamp,+ @Parameter(description = "Exclusive upper bound for the sent timestamp, in Unix milliseconds.", example = "1767312000000") @QueryParam("to") Long toTimestamp,+ @Parameter(description = "Count notifications associated with this realm.", example = EXAMPLE_REALM) @QueryParam("realmId") String realmId,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @QueryParam("userId") String userId,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @QueryParam("assetId") String assetId,+ @Parameter(description = "Origin that created the notification.") @QueryParam("source") Notification.Source source);}diff --git a/model/src/main/java/org/openremote/model/notification/SentNotification.java b/model/src/main/java/org/openremote/model/notification/SentNotification.javaindex b6c7354ef..44bfb6cad 100644--- a/model/src/main/java/org/openremote/model/notification/SentNotification.java+++ b/model/src/main/java/org/openremote/model/notification/SentNotification.java@@ -19,6 +19,7 @@*/package org.openremote.model.notification;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.persistence.*;import jakarta.validation.constraints.NotNull;import org.hibernate.annotations.JdbcTypeCode;@@ -30,6 +31,7 @@ import static org.openremote.model.Constants.PERSISTENCE_SEQUENCE_ID_GENERATOR;@Entity@Table(name = "NOTIFICATION")+@Schema(description = "One target-specific notification delivery record, including delivery and acknowledgement state.")public class SentNotification {/**@@ -48,53 +50,67 @@ public class SentNotification {@Column(name = "ID")@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = PERSISTENCE_SEQUENCE_ID_GENERATOR)@SequenceGenerator(name = PERSISTENCE_SEQUENCE_ID_GENERATOR, initialValue = 1000, allocationSize = 1)+ @Schema(description = "Server-assigned numeric delivery-record identifier.", accessMode = Schema.AccessMode.READ_ONLY, example = "42")protected Long id;@Column(name = "NAME")+ @Schema(description = "Human-readable notification name.", example = "High temperature alert")protected String name;@NotNull@Column(name = "TYPE", nullable = false, length = 50)+ @Schema(description = "Notification message type discriminator.", example = "push")protected String type;@NotNull@Column(name = "TARGET", length = 50)@Enumerated(EnumType.STRING)+ @Schema(description = "Kind of delivery target.")protected Notification.TargetType target;@NotNull@Column(name = "TARGET_ID")+ @Schema(description = "User, asset, realm, or custom target identifier.")protected String targetId;@NotNull()@Column(name = "SOURCE", length = 50)@Enumerated(EnumType.STRING)+ @Schema(description = "Kind of actor that created the notification.")protected Notification.Source source;@NotNull@Column(name = "REALM", nullable = false, updatable = false)+ @Schema(description = "Realm associated with the delivery record.", example = "building")protected String realm;@Column(name = "SOURCE_ID", length = 43)+ @Schema(description = "Identifier of the user, rule, or component that created the notification.")protected String sourceId;@Column(name = "MESSAGE")@JdbcTypeCode(SqlTypes.JSON)+ @Schema(description = "Typed message payload as it was submitted.")protected AbstractNotificationMessage message;@Column(name = "ERROR", length = 4096)+ @Schema(description = "Delivery error detail when sending failed.")protected String error;@Column(name = "SENT_ON", updatable = false, nullable = false, columnDefinition = "TIMESTAMP WITH TIME ZONE")+ @Schema(description = "Time the notification was sent or attempted.", accessMode = Schema.AccessMode.READ_ONLY)protected Instant sentOn;@Column(name = "DELIVERED_ON", columnDefinition = "TIMESTAMP WITH TIME ZONE")+ @Schema(description = "Time the target marked the notification delivered.", accessMode = Schema.AccessMode.READ_ONLY)protected Instant deliveredOn;@Column(name = "ACKNOWLEDGED_ON", columnDefinition = "TIMESTAMP WITH TIME ZONE")+ @Schema(description = "Time the target acknowledged the notification.", accessMode = Schema.AccessMode.READ_ONLY)protected Instant acknowledgedOn;@Column(name = "ACKNOWLEDGEMENT")+ @Schema(description = "Optional JSON acknowledgement value serialized as text.")protected String acknowledgement;public Long getId() {diff --git a/model/src/main/java/org/openremote/model/provisioning/ProvisioningConfig.java b/model/src/main/java/org/openremote/model/provisioning/ProvisioningConfig.javaindex 77fa1db42..1acd514ee 100644--- a/model/src/main/java/org/openremote/model/provisioning/ProvisioningConfig.java+++ b/model/src/main/java/org/openremote/model/provisioning/ProvisioningConfig.java@@ -23,6 +23,7 @@ import com.fasterxml.jackson.annotation.JsonProperty;import com.fasterxml.jackson.annotation.JsonSubTypes;import com.fasterxml.jackson.annotation.JsonTypeInfo;import com.fasterxml.jackson.databind.annotation.JsonDeserialize;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.persistence.*;import jakarta.validation.constraints.Min;import jakarta.validation.constraints.NotNull;@@ -43,6 +44,7 @@ import static org.openremote.model.Constants.PERSISTENCE_SEQUENCE_ID_GENERATOR;@JsonSubTypes(@JsonSubTypes.Type(name = "x509", value = X509ProvisioningConfig.class))+@Schema(description = "Polymorphic device-provisioning configuration. The type discriminator selects the provisioning mechanism.")public abstract class ProvisioningConfig<T, U extends ProvisioningConfig<T, U>> {public static final String DISABLED_PROPERTY_NAME = "disabled";@@ -53,6 +55,7 @@ public abstract class ProvisioningConfig<T, U extends ProvisioningConfig<T, U>>@Min(1)@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = PERSISTENCE_SEQUENCE_ID_GENERATOR)@SequenceGenerator(name = PERSISTENCE_SEQUENCE_ID_GENERATOR, initialValue = 1000, allocationSize = 1)+ @Schema(description = "Server-assigned numeric configuration identifier.", accessMode = Schema.AccessMode.READ_ONLY, example = "12")protected Long id;@Column(name = "CREATED_ON", updatable = false, nullable = false, columnDefinition= "TIMESTAMP WITH TIME ZONE")@@ -65,27 +68,34 @@ public abstract class ProvisioningConfig<T, U extends ProvisioningConfig<T, U>>@NotNull@Column(name = "NAME", nullable = false)@Size(min = 1, max = 255, message = "{ProvisioningConfig.name.Size}")+ @Schema(description = "Human-readable configuration name.", example = "Factory sensors")protected String name;@Column(name = "TYPE", nullable = false, updatable = false, insertable = false, length = 100, columnDefinition = "char(100)")@Size(min = 3, max = 100, message = "{ProvisioningConfig.type.Size}")@JsonDeserialize+ @Schema(description = "Provisioning mechanism discriminator.", example = "x509")protected String type;@Column(name = "REALM", nullable = false, updatable = false)+ @Schema(description = "Realm in which devices and users are provisioned.", example = "building")protected String realm;@Column(name = "ASSET_TEMPLATE", columnDefinition = "text")+ @Schema(description = "Optional asset JSON template applied to newly provisioned devices.")protected String assetTemplate;@Column(name = "RESTRICTED_USER", nullable = false)+ @Schema(description = "Create the provisioned user with restricted-user access.", example = "true")protected boolean restrictedUser;@Column(name = "ROLES")@Enumerated(EnumType.STRING)+ @Schema(description = "Client roles granted to the provisioned user.")protected ClientRole[] userRoles;@Column(name = DISABLED_PROPERTY_NAME, nullable = false)+ @Schema(description = "Prevent new provisioning while retaining the configuration.", example = "false")protected boolean disabled = false;protected ProvisioningConfig() {}diff --git a/model/src/main/java/org/openremote/model/provisioning/ProvisioningResource.java b/model/src/main/java/org/openremote/model/provisioning/ProvisioningResource.javaindex 54f713985..d0c392375 100644--- a/model/src/main/java/org/openremote/model/provisioning/ProvisioningResource.java+++ b/model/src/main/java/org/openremote/model/provisioning/ProvisioningResource.java@@ -20,7 +20,10 @@package org.openremote.model.provisioning;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.parameters.RequestBody;import io.swagger.v3.oas.annotations.tags.Tag;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.validation.Valid;@@ -28,30 +31,50 @@ import jakarta.ws.rs.*;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;-@Tag(name = "Provisioning", description = "Operations on provisioning configurations")+@Tag(name = "Provisioning", description = "Super-administrator operations for device provisioning configurations")@Path("provisioning")public interface ProvisioningResource {@GET@Produces(APPLICATION_JSON)- @Operation(operationId = "getProvisioningConfigs", summary = "Retrieve all provisioning configurations")+ @Operation(operationId = "getProvisioningConfigs", summary = "Retrieve all provisioning configurations",+ description = "Returns every provisioning configuration. This operation is restricted to a super administrator.")+ @OpenApiResponses.Ok+ @OpenApiResponses.AuthenticatedProvisioningConfig<?, ?>[] getProvisioningConfigs();@POST@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)- @Operation(operationId = "createProvisioningConfig", summary = "Create a provisioning configuration")- long createProvisioningConfig(ProvisioningConfig<?, ?> provisioningConfig);+ @Operation(operationId = "createProvisioningConfig", summary = "Create a provisioning configuration",+ description = "Persists a new provisioning configuration and returns its generated numeric identifier. This operation is restricted to a super administrator.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ long createProvisioningConfig(+ @RequestBody(required = true, description = "Complete typed provisioning configuration to create.") ProvisioningConfig<?, ?> provisioningConfig);@PUT@Path("{id}")@Consumes(APPLICATION_JSON)- @Operation(operationId = "updateProvisioningConfig", summary = "Update a provisioning configuration")- void updateProvisioningConfig(@BeanParam RequestParams requestParams, @PathParam("id") Long id, @Valid ProvisioningConfig<?, ?> provisioningConfig);+ @Operation(operationId = "updateProvisioningConfig", summary = "Update a provisioning configuration",+ description = "Replaces the provisioning configuration identified by the path. This operation is restricted to a super administrator.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ void updateProvisioningConfig(+ @BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric provisioning configuration identifier.", example = "12") @PathParam("id") Long id,+ @Valid @RequestBody(required = true, description = "Complete typed provisioning configuration to replace the existing configuration.") ProvisioningConfig<?, ?> provisioningConfig);@DELETE@Path("{id}")@Produces(APPLICATION_JSON)- @Operation(operationId = "deleteProvisioningConfig", summary = "Delete a provisioning configuration")- void deleteProvisioningConfig(@BeanParam RequestParams requestParams, @PathParam("id") Long id);+ @Operation(operationId = "deleteProvisioningConfig", summary = "Delete a provisioning configuration",+ description = "Permanently removes the provisioning configuration identified by the path. This operation is restricted to a super administrator.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ void deleteProvisioningConfig(+ @BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric provisioning configuration identifier.", example = "12") @PathParam("id") Long id);}diff --git a/model/src/main/java/org/openremote/model/query/AssetQuery.java b/model/src/main/java/org/openremote/model/query/AssetQuery.javaindex 65b3968e4..a44d571f7 100644--- a/model/src/main/java/org/openremote/model/query/AssetQuery.java+++ b/model/src/main/java/org/openremote/model/query/AssetQuery.java@@ -19,6 +19,7 @@*/package org.openremote.model.query;+import io.swagger.v3.oas.annotations.media.Schema;import org.openremote.model.asset.Asset;import org.openremote.model.asset.AssetDescriptor;import org.openremote.model.query.filter.*;@@ -31,10 +32,13 @@ import java.util.stream.Collectors;/*** Encapsulate asset query restriction, projection, and ordering of results.*/+@Schema(description = "Composable asset search request. Populated filters are combined to restrict results; limit and offset provide pagination.")public class AssetQuery implements Serializable {+ @Schema(name = "AssetQuerySelect", description = "Response projection for controlling which asset attributes are returned.")public static class Select {protected static final String[] EMPTY_ATTRIBUTES = new String[0];+ @Schema(description = "Attribute names to include. An empty array excludes all attributes; null returns all attributes.", example = "[\"temperature\",\"humidity\"]")public String[] attributes;public Select attributes(String... attributeNames) {@@ -55,6 +59,7 @@ public class AssetQuery implements Serializable {}}+ @Schema(name = "AssetQueryOrderBy", description = "Asset result ordering.")public static class OrderBy {public enum Property {@@ -65,7 +70,9 @@ public class AssetQuery implements Serializable {REALM}+ @Schema(description = "Asset property used for ordering.", example = "NAME")public Property property;+ @Schema(description = "Reverse the default ascending order.", example = "false")public boolean descending;public OrderBy() {@@ -168,22 +175,29 @@ public class AssetQuery implements Serializable {}}+ @Schema(description = "When parent or path filters are used, include matching descendants.", example = "true")public boolean recursive;// Projectionpublic Select select;// Restriction predicates+ @Schema(description = "Requested visibility class relative to the caller.")public Access access;+ @Schema(description = "Match these exact asset identifiers.")public String[] ids;public StringPredicate[] names;public ParentPredicate[] parents;public PathPredicate[] paths;public RealmPredicate realm;+ @Schema(description = "Match assets linked to any of these users.")public String[] userIds;+ @Schema(description = "Match registered asset type names; base types include their concrete subtypes.", example = "[\"ThingAsset\"]")public String[] types;public LogicGroup<AttributePredicate> attributes;// Orderingpublic OrderBy orderBy;+ @Schema(description = "Maximum number of results; zero uses the server default.", example = "100")public int limit;+ @Schema(description = "Number of matching results to skip.", example = "0")public int offset;public AssetQuery() {diff --git a/model/src/main/java/org/openremote/model/query/UserQuery.java b/model/src/main/java/org/openremote/model/query/UserQuery.javaindex 513bc8421..3b18b3515 100644--- a/model/src/main/java/org/openremote/model/query/UserQuery.java+++ b/model/src/main/java/org/openremote/model/query/UserQuery.java@@ -1,17 +1,23 @@package org.openremote.model.query;import com.fasterxml.jackson.annotation.JsonCreator;+import io.swagger.v3.oas.annotations.media.Schema;import org.openremote.model.query.filter.PathPredicate;import org.openremote.model.query.filter.RealmPredicate;import org.openremote.model.query.filter.StringPredicate;import java.util.Arrays;+@Schema(description = "Composable identity-provider user search request. Populated restrictions are combined, except role arrays which match any supplied role.")public class UserQuery {+ @Schema(description = "Predicate for matching an identity-provider user attribute by name and optional value.")public static class AttributeValuePredicate {+ @Schema(description = "Invert this attribute predicate.", example = "false")public boolean negated;+ @Schema(description = "Attribute-name matcher.")public StringPredicate name;+ @Schema(description = "Optional attribute-value matcher.")public StringPredicate value;public AttributeValuePredicate(boolean negated, StringPredicate name) {@@ -63,7 +69,9 @@ public class UserQuery {}}+ @Schema(name = "UserQuerySelect", description = "User response projection.")public static class Select {+ @Schema(description = "Return basic identity fields only, omitting administrative details.", example = "true")public boolean basic;public Select basic(boolean basic) {@@ -79,6 +87,7 @@ public class UserQuery {}}+ @Schema(name = "UserQueryOrderBy", description = "User result ordering.")public static class OrderBy {public enum Property {@@ -89,7 +98,9 @@ public class UserQuery {}+ @Schema(description = "User property used for ordering.", example = "USERNAME")public Property property;+ @Schema(description = "Reverse the default ascending order.", example = "false")public boolean descending;public OrderBy() {@@ -125,22 +136,28 @@ public class UserQuery {// Restriction predicatespublic RealmPredicate realmPredicate;+ @Schema(description = "Match users linked to any of these asset identifiers.")public String[] assets;public PathPredicate pathPredicate;+ @Schema(description = "Match these exact identity-provider user identifiers.")public String[] ids;public Select select;public StringPredicate[] usernames;/*** AND condition is assumed between values*/+ @Schema(description = "Attribute predicates combined with AND.")public AttributeValuePredicate[] attributes;/*** OR condition is assumed between values (AND filtering can be applied by the caller on the results)*/public StringPredicate[] clientRoles;public StringPredicate[] realmRoles;+ @Schema(description = "True selects service users, false selects human users, null includes both.", nullable = true)public Boolean serviceUsers;+ @Schema(description = "Maximum number of results.", example = "100")public Integer limit;+ @Schema(description = "Number of matching results to skip.", example = "0")public Integer offset;public OrderBy orderBy;diff --git a/model/src/main/java/org/openremote/model/query/filter/ParentPredicate.java b/model/src/main/java/org/openremote/model/query/filter/ParentPredicate.javaindex 592b0e2a4..4396a80a0 100644--- a/model/src/main/java/org/openremote/model/query/filter/ParentPredicate.java+++ b/model/src/main/java/org/openremote/model/query/filter/ParentPredicate.java@@ -19,8 +19,12 @@*/package org.openremote.model.query.filter;+import io.swagger.v3.oas.annotations.media.Schema;++@Schema(description = "Matches assets by direct parent identifier; a null id represents root assets.")public class ParentPredicate {+ @Schema(description = "Direct parent asset identifier; null selects root assets.", nullable = true)public String id;public ParentPredicate() {diff --git a/model/src/main/java/org/openremote/model/query/filter/PathPredicate.java b/model/src/main/java/org/openremote/model/query/filter/PathPredicate.javaindex 79e7b66b2..4571f5154 100644--- a/model/src/main/java/org/openremote/model/query/filter/PathPredicate.java+++ b/model/src/main/java/org/openremote/model/query/filter/PathPredicate.java@@ -19,10 +19,14 @@*/package org.openremote.model.query.filter;+import io.swagger.v3.oas.annotations.media.Schema;+import java.util.Arrays;+@Schema(description = "Matches an asset ancestry path represented as ordered asset identifiers.")public class PathPredicate {+ @Schema(description = "Ordered asset identifiers in the ancestry path.")public String[] path;public PathPredicate() {diff --git a/model/src/main/java/org/openremote/model/query/filter/RealmPredicate.java b/model/src/main/java/org/openremote/model/query/filter/RealmPredicate.javaindex 207b8c81d..33e323fe5 100644--- a/model/src/main/java/org/openremote/model/query/filter/RealmPredicate.java+++ b/model/src/main/java/org/openremote/model/query/filter/RealmPredicate.java@@ -21,9 +21,12 @@ package org.openremote.model.query.filter;import com.fasterxml.jackson.annotation.JsonCreator;import com.fasterxml.jackson.annotation.JsonProperty;+import io.swagger.v3.oas.annotations.media.Schema;+@Schema(description = "Matches an exact realm name.")public class RealmPredicate {+ @Schema(description = "Realm name.", example = "building")public String name;@JsonCreatordiff --git a/model/src/main/java/org/openremote/model/query/filter/StringPredicate.java b/model/src/main/java/org/openremote/model/query/filter/StringPredicate.javaindex e9eb4f74e..9585f00e8 100644--- a/model/src/main/java/org/openremote/model/query/filter/StringPredicate.java+++ b/model/src/main/java/org/openremote/model/query/filter/StringPredicate.java@@ -19,6 +19,7 @@*/package org.openremote.model.query.filter;+import io.swagger.v3.oas.annotations.media.Schema;import org.openremote.model.util.JSONSchemaUtil.*;import org.openremote.model.query.AssetQuery;import org.openremote.model.util.ValueUtil;@@ -33,6 +34,7 @@ import java.util.function.Supplier;* Predicate for string values; will match based on configured options.*/@JsonSchemaDescription("Predicate for string values; will match based on configured options.")+@Schema(description = "String matcher supporting exact, prefix, suffix, or contains matching, case sensitivity, and negation.")public class StringPredicate extends ValuePredicate {public static final String name = "string";diff --git a/model/src/main/java/org/openremote/model/rules/RulesResource.java b/model/src/main/java/org/openremote/model/rules/RulesResource.javaindex 3e5656c82..a581b8a92 100644--- a/model/src/main/java/org/openremote/model/rules/RulesResource.java+++ b/model/src/main/java/org/openremote/model/rules/RulesResource.java@@ -20,8 +20,17 @@package org.openremote.model.rules;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.enums.Explode;+import io.swagger.v3.oas.annotations.enums.ParameterStyle;+import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.ExampleObject;+import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.parameters.RequestBody;+import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.Constants;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import org.openremote.model.rules.geofence.GeofenceDefinition;import jakarta.annotation.security.RolesAllowed;@@ -31,8 +40,10 @@ import jakarta.ws.rs.*;import java.util.List;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.*;+import static org.openremote.model.http.OpenApiExamples.ASSET_RULESET_CREATE;-@Tag(name = "Rule", description = "Operations on rules")+@Tag(name = "Rule", description = "Inspect rule engines and query or manage global, realm, and asset rulesets")@Path("rules")public interface RulesResource {@@ -43,7 +54,11 @@ public interface RulesResource {@Produces(APPLICATION_JSON)@Path("info/global")@RolesAllowed({Constants.READ_RULES_ROLE})- @Operation(operationId = "getGlobalEngineInfo", summary = "Retrieve information about the global rules engine")+ @Operation(operationId = "getGlobalEngineInfo", summary = "Retrieve information about the global rules engine",+ description = "Returns runtime status and compilation/execution error counts for the global engine, or null when that engine is not running. Super-user access is required.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @ApiResponse(responseCode = "204", description = "The global rules engine is not running")RulesEngineInfo getGlobalEngineInfo(@BeanParam RequestParams requestParams);/**@@ -53,8 +68,13 @@ public interface RulesResource {@Produces(APPLICATION_JSON)@Path("info/realm/{realm}")@RolesAllowed({Constants.READ_RULES_ROLE})- @Operation(operationId = "getRealmEngineInfo", summary = "Retrieve information about a realm rules engine")- RulesEngineInfo getRealmEngineInfo(@BeanParam RequestParams requestParams, @PathParam("realm") String realm);+ @Operation(operationId = "getRealmEngineInfo", summary = "Retrieve information about a realm rules engine",+ description = "Returns runtime status and error counts for an accessible realm engine, or null when that engine is not running. Restricted users cannot inspect realm engines.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @ApiResponse(responseCode = "204", description = "The requested realm rules engine is not running")+ RulesEngineInfo getRealmEngineInfo(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm);/*** Retrieve information about the specified asset rules engine (if engine doesn't exist then will return null).@@ -63,8 +83,13 @@ public interface RulesResource {@Produces(APPLICATION_JSON)@Path("info/asset/{assetId}")@RolesAllowed({Constants.READ_RULES_ROLE})- @Operation(operationId = "getAssetEngineInfo", summary = "Retrieve information about an asset rules engine")- RulesEngineInfo getAssetEngineInfo(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId);+ @Operation(operationId = "getAssetEngineInfo", summary = "Retrieve information about an asset rules engine",+ description = "Returns runtime status and error counts for an accessible asset engine. Returns null when the asset or its engine does not exist.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @ApiResponse(responseCode = "204", description = "The asset or its rules engine does not exist")+ RulesEngineInfo getAssetEngineInfo(@BeanParam RequestParams requestParams,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId);/*** Retrieve global rules. Only the superuser can perform this operation, a 403 status is returned if a regular user@@ -73,8 +98,15 @@ public interface RulesResource {@GET@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_RULES_ROLE})- @Operation(operationId = "getGlobalRulesets", summary = " Retrieve the global rules")- GlobalRuleset[] getGlobalRulesets(@BeanParam RequestParams requestParams, @QueryParam("language") List<Ruleset.Lang> languages, @QueryParam("fullyPopulate") boolean fullyPopulate);+ @Operation(operationId = "getGlobalRulesets", summary = "Retrieve global rulesets",+ description = "Returns global rulesets filtered by repeated language parameters. fullyPopulate controls whether rule source and other large fields are loaded; super-user access is required.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ GlobalRuleset[] getGlobalRulesets(+ @BeanParam RequestParams requestParams,+ @Parameter(description = "Rule languages to include; repeat the query parameter for multiple values.", style = ParameterStyle.FORM, explode = Explode.TRUE) @QueryParam("language") List<Ruleset.Lang> languages,+ @Parameter(description = "Include rule source, meta, and other large fields instead of summary records.", example = "true") @QueryParam("fullyPopulate") boolean fullyPopulate);/*** Retrieve rules of a realm. The superuser can retrieve rules of all realms, a 403 status is returned if a regular@@ -84,8 +116,16 @@ public interface RulesResource {@GET@Path("realm/for/{realm}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getRealmRulesets", summary = "Retrieve the rules of a realm")- RealmRuleset[] getRealmRulesets(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @QueryParam("language") List<Ruleset.Lang> languages, @QueryParam("fullyPopulate") boolean fullyPopulate);+ @Operation(operationId = "getRealmRulesets", summary = "Retrieve rulesets for a realm",+ description = "Returns realm rulesets filtered by language. Anonymous, restricted, or callers without read-rules permission receive public rulesets only; fullyPopulate controls loading of rule source.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ RealmRuleset[] getRealmRulesets(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = "Rule languages to include; repeat the query parameter for multiple values.", style = ParameterStyle.FORM, explode = Explode.TRUE) @QueryParam("language") List<Ruleset.Lang> languages,+ @Parameter(description = "Include rule source, meta, and other large fields instead of summary records.", example = "true") @QueryParam("fullyPopulate") boolean fullyPopulate);/*** Retrieve rules of an asset. The superuser can retrieve rules of all realms and assets, a 403 status is returned@@ -95,8 +135,16 @@ public interface RulesResource {@GET@Path("asset/for/{assetId}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getAssetRulesets", summary = "Retrieve the rules of an asset")- AssetRuleset[] getAssetRulesets(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId, @QueryParam("language") List<Ruleset.Lang> languages, @QueryParam("fullyPopulate") boolean fullyPopulate);+ @Operation(operationId = "getAssetRulesets", summary = "Retrieve rulesets for an asset",+ description = "Returns asset rulesets filtered by language. Callers without full access receive public rulesets only; a nonexistent asset produces an empty array.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Forbidden+ AssetRuleset[] getAssetRulesets(+ @BeanParam RequestParams requestParams,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId,+ @Parameter(description = "Rule languages to include; repeat the query parameter for multiple values.", style = ParameterStyle.FORM, explode = Explode.TRUE) @QueryParam("language") List<Ruleset.Lang> languages,+ @Parameter(description = "Include rule source, meta, and other large fields instead of summary records.", example = "true") @QueryParam("fullyPopulate") boolean fullyPopulate);/* ################################################################################################# */@@ -108,8 +156,13 @@ public interface RulesResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_RULES_ROLE})- @Operation(operationId = "createGlobalRuleset", summary = "Create a global ruleset")- long createGlobalRuleset(@BeanParam RequestParams requestParams, @Valid GlobalRuleset ruleset);+ @Operation(operationId = "createGlobalRuleset", summary = "Create a global ruleset",+ description = "Creates and deploys a global ruleset and returns its numeric ID. Super-user access is required; legacy JavaScript rulesets cannot be created.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ long createGlobalRuleset(@BeanParam RequestParams requestParams,+ @Valid @RequestBody(required = true, description = "Global ruleset name, language, source, enabled state, and optional metadata.") GlobalRuleset ruleset);/*** Retrieve a global ruleset. Only the superuser can perform this operation, a 403 status is returned if a regular@@ -119,8 +172,13 @@ public interface RulesResource {@Path("{id}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_RULES_ROLE})- @Operation(operationId = "getGlobalRuleset", summary = "Retrieve a global ruleset")- GlobalRuleset getGlobalRuleset(@BeanParam RequestParams requestParams, @PathParam("id") Long id);+ @Operation(operationId = "getGlobalRuleset", summary = "Retrieve a global ruleset",+ description = "Returns one fully populated global ruleset including transient deployment status and errors. Super-user access is required.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.NotFound+ GlobalRuleset getGlobalRuleset(@BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric ruleset identifier.", example = "27") @PathParam("id") Long id);/*** Update a global ruleset. Only the superuser can perform this operation, a 403 status is returned if a@@ -130,8 +188,16 @@ public interface RulesResource {@Path("{id}")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_RULES_ROLE})- @Operation(operationId = "updateGlobalRuleset", summary = "Update a global ruleset")- void updateGlobalRuleset(@BeanParam RequestParams requestParams, @PathParam("id") Long id, @Valid GlobalRuleset ruleset);+ @Operation(operationId = "updateGlobalRuleset", summary = "Update a global ruleset",+ description = "Replaces and redeploys the identified global ruleset. Path and body IDs must match; legacy JavaScript rulesets cannot be updated.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ void updateGlobalRuleset(+ @BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric ruleset identifier; must match the body id.", example = "27") @PathParam("id") Long id,+ @Valid @RequestBody(required = true, description = "Complete replacement global ruleset; its id must match the path.") GlobalRuleset ruleset);/*** Deletes a global ruleset. Only the superuser can perform this operation, a 403 status is returned if a regular@@ -141,8 +207,13 @@ public interface RulesResource {@Path("{id}")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_RULES_ROLE})- @Operation(operationId = "deleteGlobalRuleset", summary = "Delete a global ruleset")- void deleteGlobalRuleset(@BeanParam RequestParams requestParams, @PathParam("id") Long id);+ @Operation(operationId = "deleteGlobalRuleset", summary = "Delete a global ruleset",+ description = "Permanently removes and undeploys one global ruleset. Super-user access is required.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.NotFound+ void deleteGlobalRuleset(@BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric ruleset identifier.", example = "27") @PathParam("id") Long id);/* ################################################################################################# */@@ -154,8 +225,13 @@ public interface RulesResource {@Path("realm")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_RULES_ROLE})- @Operation(operationId = "createRealmRuleset", summary = "Create a realm ruleset")- long createRealmRuleset(@BeanParam RequestParams requestParams, @Valid RealmRuleset ruleset);+ @Operation(operationId = "createRealmRuleset", summary = "Create a realm ruleset",+ description = "Creates and deploys a ruleset in its body realm and returns its numeric ID. Restricted users cannot create realm rulesets; legacy JavaScript is not accepted.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ long createRealmRuleset(@BeanParam RequestParams requestParams,+ @Valid @RequestBody(required = true, description = "Realm ruleset including its target realm, name, language, source, and enabled state.") RealmRuleset ruleset);/*** Retrieve a realm ruleset. The superuser can retrieve rules of all realms, a 403 status is returned if a regular@@ -165,8 +241,13 @@ public interface RulesResource {@Path("realm/{id}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_RULES_ROLE})- @Operation(operationId = "getRealmRuleset", summary = "Retrieve a realm ruleset")- RealmRuleset getRealmRuleset(@BeanParam RequestParams requestParams, @PathParam("id") Long id);+ @Operation(operationId = "getRealmRuleset", summary = "Retrieve a realm ruleset",+ description = "Returns one fully populated realm ruleset when its realm is accessible to the caller.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.NotFound+ RealmRuleset getRealmRuleset(@BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric ruleset identifier.", example = "27") @PathParam("id") Long id);/*** Update a realm ruleset. The superuser can update rules of all realms, a 403 status is returned if a regular user@@ -176,8 +257,16 @@ public interface RulesResource {@Path("realm/{id}")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_RULES_ROLE})- @Operation(operationId = "updateRealmRuleset", summary = "Update a realm ruleset")- void updateRealmRuleset(@BeanParam RequestParams requestParams, @PathParam("id") Long id, @Valid RealmRuleset ruleset);+ @Operation(operationId = "updateRealmRuleset", summary = "Update a realm ruleset",+ description = "Replaces and redeploys one realm ruleset. Path and body IDs and the existing realm must match; legacy JavaScript cannot be updated.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ void updateRealmRuleset(+ @BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric ruleset identifier; must match the body id.", example = "27") @PathParam("id") Long id,+ @Valid @RequestBody(required = true, description = "Complete replacement realm ruleset; its id and realm must match the existing ruleset.") RealmRuleset ruleset);/*** Delete a realm ruleset. The superuser can delete rules of all realms, a 403 status is returned if a regular user@@ -187,8 +276,13 @@ public interface RulesResource {@Path("realm/{id}")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_RULES_ROLE})- @Operation(operationId = "deleteRealmRuleset", summary = "Delete a realm ruleset")- void deleteRealmRuleset(@BeanParam RequestParams requestParams, @PathParam("id") Long id);+ @Operation(operationId = "deleteRealmRuleset", summary = "Delete a realm ruleset",+ description = "Permanently removes and undeploys one ruleset from an accessible realm.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.NotFound+ void deleteRealmRuleset(@BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric ruleset identifier.", example = "27") @PathParam("id") Long id);/* ################################################################################################# */@@ -202,8 +296,16 @@ public interface RulesResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_RULES_ROLE})- @Operation(operationId = "createAssetRuleset", summary = "Create an asset ruleset")- long createAssetRuleset(@BeanParam RequestParams requestParams, @Valid AssetRuleset ruleset);+ @Operation(operationId = "createAssetRuleset", summary = "Create an asset ruleset",+ description = "Creates and deploys a ruleset for an accessible asset and returns its numeric ID. The assetId is taken from the request body.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ long createAssetRuleset(@BeanParam RequestParams requestParams,+ @Valid @RequestBody(required = true, description = "Asset ruleset including its target assetId, name, language, source, and enabled state.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = AssetRuleset.class),+ examples = @ExampleObject(name = "Asset alert ruleset", summary = "Create an enabled JSON ruleset for one asset", value = ASSET_RULESET_CREATE))) AssetRuleset ruleset);/*** Retrieve an asset ruleset. The superuser can retrieve rules of all assets, a 403 status is returned if a regular@@ -214,8 +316,13 @@ public interface RulesResource {@Path("asset/{id}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_RULES_ROLE})- @Operation(operationId = "getAssetRuleset", summary = "Retrieve an asset ruleset")- AssetRuleset getAssetRuleset(@BeanParam RequestParams requestParams, @PathParam("id") Long id);+ @Operation(operationId = "getAssetRuleset", summary = "Retrieve an asset ruleset",+ description = "Returns one fully populated asset ruleset when the caller can access its realm and owning asset.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.NotFound+ AssetRuleset getAssetRuleset(@BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric ruleset identifier.", example = "27") @PathParam("id") Long id);/*** Update an asset ruleset. The superuser can update rules of all assets, a 403 status is returned if a regular user@@ -226,8 +333,16 @@ public interface RulesResource {@Path("asset/{id}")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_RULES_ROLE})- @Operation(operationId = "updateAssetRuleset", summary = "Update an asset ruleset")- void updateAssetRuleset(@BeanParam RequestParams requestParams, @PathParam("id") Long id, @Valid AssetRuleset ruleset);+ @Operation(operationId = "updateAssetRuleset", summary = "Update an asset ruleset",+ description = "Replaces and redeploys one asset ruleset. The ID must match and an existing ruleset cannot be reassigned to another asset.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ void updateAssetRuleset(+ @BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric ruleset identifier; must match the body id.", example = "27") @PathParam("id") Long id,+ @Valid @RequestBody(required = true, description = "Complete replacement asset ruleset; its id and assetId must match the existing ruleset.") AssetRuleset ruleset);/*** Delete an asset ruleset. The superuser can delete rules of all assets, a 403 status is returned if a regular user@@ -238,8 +353,13 @@ public interface RulesResource {@Path("asset/{id}")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_RULES_ROLE})- @Operation(operationId = "deleteAssetRuleset", summary = "Delete an asset ruleset")- void deleteAssetRuleset(@BeanParam RequestParams requestParams, @PathParam("id") Long id);+ @Operation(operationId = "deleteAssetRuleset", summary = "Delete an asset ruleset",+ description = "Permanently removes and undeploys one ruleset from an accessible asset.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.NotFound+ void deleteAssetRuleset(@BeanParam RequestParams requestParams,+ @Parameter(description = "Numeric ruleset identifier.", example = "27") @PathParam("id") Long id);/*** Get the geofences for the specified asset; if this method is accessed anonymously (public read) then the asset@@ -249,6 +369,11 @@ public interface RulesResource {@GET@Path("geofences/{assetId}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getAssetGeofences", summary = "Get the geofences of an asset")- GeofenceDefinition[] getAssetGeofences(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId);+ @Operation(operationId = "getAssetGeofences", summary = "Retrieve geofences for an asset",+ description = "Extracts geofence definitions relevant to the asset. Anonymous access requires a public-readable asset; authenticated restricted users require an asset link.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Forbidden+ @OpenApiResponses.NotFound+ GeofenceDefinition[] getAssetGeofences(@BeanParam RequestParams requestParams,+ @Parameter(description = ASSET_ID, example = EXAMPLE_ASSET_ID) @PathParam("assetId") String assetId);}diff --git a/model/src/main/java/org/openremote/model/rules/Ruleset.java b/model/src/main/java/org/openremote/model/rules/Ruleset.javaindex aac962167..08d79cbb3 100644--- a/model/src/main/java/org/openremote/model/rules/Ruleset.java+++ b/model/src/main/java/org/openremote/model/rules/Ruleset.java@@ -22,6 +22,7 @@ package org.openremote.model.rules;import com.fasterxml.jackson.annotation.JsonIgnore;import com.fasterxml.jackson.annotation.JsonSubTypes;import com.fasterxml.jackson.annotation.JsonTypeInfo;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.persistence.*;import jakarta.validation.constraints.NotNull;import jakarta.validation.constraints.Size;@@ -50,6 +51,7 @@ import static org.openremote.model.Constants.PERSISTENCE_SEQUENCE_ID_GENERATOR;@JsonSubTypes.Type(value = RealmRuleset.class, name = RealmRuleset.TYPE),@JsonSubTypes.Type(value = GlobalRuleset.class, name = GlobalRuleset.TYPE)})+@Schema(description = "Executable ruleset. Its type discriminator selects global, realm, or asset scope.")public abstract class Ruleset {public static final String SHOW_ON_LIST = "showOnList";@@ -68,44 +70,55 @@ public abstract class Ruleset {@Column(name = "ID")@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = PERSISTENCE_SEQUENCE_ID_GENERATOR)@SequenceGenerator(name = PERSISTENCE_SEQUENCE_ID_GENERATOR, initialValue = 1000, allocationSize = 1)+ @Schema(description = "Server-assigned numeric ruleset identifier.", accessMode = Schema.AccessMode.READ_ONLY, example = "27")protected Long id;@Version@Column(name = "VERSION", nullable = false)+ @Schema(description = "Optimistic-lock version.", accessMode = Schema.AccessMode.READ_ONLY, example = "2")protected long version;@Column(name = "CREATED_ON", updatable = false, nullable = false, columnDefinition= "TIMESTAMP WITH TIME ZONE")@org.hibernate.annotations.CreationTimestamp+ @Schema(description = "Server-assigned creation time.", accessMode = Schema.AccessMode.READ_ONLY)protected Instant createdOn = Instant.now();@Column(name = "LAST_MODIFIED", nullable = false, columnDefinition= "TIMESTAMP WITH TIME ZONE")@org.hibernate.annotations.UpdateTimestamp+ @Schema(description = "Server-assigned last modification time.", accessMode = Schema.AccessMode.READ_ONLY)protected Instant lastModified;@NotNull(message = "{Ruleset.name.NotNull}")@Column(name = "NAME", nullable = false)@Size(min = 3, max = 255, message = "{Ruleset.name.Size}")+ @Schema(description = "Human-readable ruleset name.", example = "High temperature alert")protected String name;@Column(name = "ENABLED", nullable = false)+ @Schema(description = "Whether the ruleset should be deployed and evaluated.", example = "true")protected boolean enabled = true;@Column(name = "RULES", nullable = false)+ @Schema(description = "Rules source encoded according to lang.")protected String rules;@NotNull@Enumerated(EnumType.STRING)@Column(name = "RULES_LANG", nullable = false)+ @Schema(description = "Rules source language. JAVASCRIPT is retained for legacy records but cannot be newly created.")protected Lang lang = Lang.GROOVY;@Column(name = "META")@JdbcTypeCode(SqlTypes.JSON)+ @Schema(description = "Optional execution and presentation metadata.")protected Map<String, Object> meta;@Transient+ @Schema(description = "Transient deployment status.", accessMode = Schema.AccessMode.READ_ONLY)protected RulesetStatus status;@Transient+ @Schema(description = "Latest compilation or execution error, when present.", accessMode = Schema.AccessMode.READ_ONLY)protected String error;protected Ruleset() {diff --git a/model/src/main/java/org/openremote/model/rules/flow/FlowResource.java b/model/src/main/java/org/openremote/model/rules/flow/FlowResource.javaindex d48338973..997a5e0c2 100644--- a/model/src/main/java/org/openremote/model/rules/flow/FlowResource.java+++ b/model/src/main/java/org/openremote/model/rules/flow/FlowResource.java@@ -1,29 +1,43 @@package org.openremote.model.rules.flow;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;import io.swagger.v3.oas.annotations.tags.Tag;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.ws.rs.*;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;-@Tag(name = "Flow", description = "Operations on flows")+@Tag(name = "Flow", description = "Discover the node definitions available to the visual flow-rules editor")@Path("flow")public interface FlowResource {@GET@Produces(APPLICATION_JSON)- @Operation(operationId = "getAllNodeDefinitions", summary = "Retrieve all node definitions")+ @Operation(operationId = "getAllNodeDefinitions", summary = "Retrieve all node definitions",+ description = "Returns every supported flow node definition except the internal LOG_OUTPUT node.")+ @OpenApiResponses.OkNode[] getAllNodeDefinitions(@BeanParam RequestParams requestParams);@GET@Path("{type}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getAllNodeDefinitionsByType", summary = "Retrieve all node definitions by type")- Node[] getAllNodeDefinitionsByType(@BeanParam RequestParams requestParams, @PathParam("type") NodeType type);+ @Operation(operationId = "getAllNodeDefinitionsByType", summary = "Retrieve all node definitions by type",+ description = "Returns supported flow node definitions whose category matches the requested node type.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ Node[] getAllNodeDefinitionsByType(+ @BeanParam RequestParams requestParams,+ @Parameter(description = "Flow node category to filter by.", example = "INPUT") @PathParam("type") NodeType type);@GET@Path("{name}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getNodeDefinition", summary = "Retrieve a node definition by name")- Node getNodeDefinition(@BeanParam RequestParams requestParams, @PathParam("name") String name);+ @Operation(operationId = "getNodeDefinition", summary = "Retrieve a node definition by name",+ description = "Resolves one flow node definition by its model name.")+ @OpenApiResponses.Ok+ @OpenApiResponses.ServerError+ Node getNodeDefinition(+ @BeanParam RequestParams requestParams,+ @Parameter(description = "Exact model name of the flow node definition.", example = "Attribute") @PathParam("name") String name);}diff --git a/model/src/main/java/org/openremote/model/security/Realm.java b/model/src/main/java/org/openremote/model/security/Realm.javaindex 928b90ac6..6a99de77a 100644--- a/model/src/main/java/org/openremote/model/security/Realm.java+++ b/model/src/main/java/org/openremote/model/security/Realm.java@@ -22,6 +22,7 @@ package org.openremote.model.security;import com.fasterxml.jackson.core.JsonParser;import com.fasterxml.jackson.databind.*;import com.fasterxml.jackson.databind.annotation.JsonDeserialize;+import io.swagger.v3.oas.annotations.media.Schema;import org.hibernate.annotations.Formula;import org.hibernate.annotations.Subselect;@@ -41,6 +42,7 @@ import static org.openremote.model.Constants.RESTRICTED_USER_REALM_ROLE;*/@Entity@Subselect("select * from PUBLIC.REALM") // Map this immutable to an SQL view, don't use/create table+@Schema(description = "Identity-provider realm and its authentication, registration, theme, token, and role settings.")public class Realm {public static final List<RealmRole> DEFAULT_REALM_ROLES = List.of(@@ -61,15 +63,19 @@ public class Realm {}@Id+ @Schema(description = "Identity-provider internal realm identifier.", accessMode = Schema.AccessMode.READ_ONLY)protected String id;@Column(name = "NAME")+ @Schema(description = "Stable realm name used in API paths and tokens.", example = "building")protected String name;@Formula("(select ra.VALUE from PUBLIC.REALM_ATTRIBUTE ra where ra.REALM_ID = ID and ra.name = 'displayName')")+ @Schema(description = "Human-readable realm label.", example = "Building Management")protected String displayName;@Column(name = "ENABLED")+ @Schema(description = "Whether users can authenticate against this realm.", example = "true")protected Boolean enabled;@Column(name = "NOT_BEFORE")@@ -82,6 +88,7 @@ public class Realm {@Column(name = "password_policy")@Convert(converter = PasswordPolicyConverter.class)@JsonDeserialize(using = PasswordPolicyDeserializer.class)+ @Schema(description = "Identity-provider password-policy rules.")protected List<String> passwordPolicy;@Column(name = "reset_password_allowed")@@ -118,10 +125,12 @@ public class Realm {protected String emailTheme;@Column(name = "access_token_lifespan")+ @Schema(description = "Access-token lifetime in seconds.", example = "300")protected Integer accessTokenLifespan;@OneToMany(fetch = FetchType.EAGER)@JoinColumn(name = "REALM_ID")+ @Schema(description = "Realm-level roles available for assignment.")protected Set<RealmRole> realmRoles;public Realm() {diff --git a/model/src/main/java/org/openremote/model/security/RealmResource.java b/model/src/main/java/org/openremote/model/security/RealmResource.javaindex ca0442110..68a9c91fd 100644--- a/model/src/main/java/org/openremote/model/security/RealmResource.java+++ b/model/src/main/java/org/openremote/model/security/RealmResource.java@@ -20,8 +20,12 @@package org.openremote.model.security;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.parameters.RequestBody;+import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.Constants;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.annotation.security.RolesAllowed;@@ -29,6 +33,8 @@ import jakarta.validation.Valid;import jakarta.ws.rs.*;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.EXAMPLE_REALM;+import static org.openremote.model.http.OpenApiDescriptions.REALM;/*** Manage realms.@@ -37,13 +43,17 @@ import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;* <p>* TODO Relax permissions to allow regular users to maintain their own realm*/-@Tag(name = "Realm", description = "Operations on realms")+@Tag(name = "Realm", description = "Discover accessible realms and administer identity-provider realms")@Path("realm")public interface RealmResource {@GET@Produces(APPLICATION_JSON)- @Operation(operationId = "getAllRealms", summary = "Retrieve all realms")+ @Operation(operationId = "getAllRealms", summary = "Retrieve all realms",+ description = "Returns complete realm records from the identity provider. This operation is restricted to a super user.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Authenticated+ @OpenApiResponses.ServerErrorRealm[] getAll(@BeanParam RequestParams requestParams);/**@@ -52,7 +62,10 @@ public interface RealmResource {@GET@Path("accessible")@Produces(APPLICATION_JSON)- @Operation(operationId = "getAccessibleRealms", summary = "Retrieve accessible realms for the authenticated user")+ @Operation(operationId = "getAccessibleRealms", summary = "Retrieve realms accessible to the caller",+ description = "Returns only realm name and display name. Super users receive all realms; authenticated users receive their realm; anonymous callers receive the request realm.")+ @OpenApiResponses.Ok+ @OpenApiResponses.ServerErrorRealm[] getAccessible(@BeanParam RequestParams requestParams);/**@@ -61,28 +74,54 @@ public interface RealmResource {@GET@Path("{name}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getRealm", summary = "Retrieve details about the currently authenticated and active realm")- Realm get(@BeanParam RequestParams requestParams, @PathParam("name") String realm);+ @Operation(operationId = "getRealm", summary = "Retrieve an accessible realm",+ description = "Returns complete details for a named active realm when it is accessible to the caller. Regular users cannot use this endpoint to inspect other realms.")+ @OpenApiResponses.Ok+ @OpenApiResponses.Forbidden+ @OpenApiResponses.NotFound+ Realm get(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("name") String realm);@PUT@Path("{name}")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "updateRealm", summary = "Update a realm")- void update(@BeanParam RequestParams requestParams, @PathParam("name") String realmName, @Valid Realm realm);+ @Operation(operationId = "updateRealm", summary = "Update a realm",+ description = "Updates a realm through the identity provider. Super-user access is required; the master realm cannot be renamed or disabled.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Conflict+ @ApiResponse(responseCode = "405", description = "The requested mutation is not allowed for the master realm")+ void update(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("name") String realmName,+ @Valid @RequestBody(required = true, description = "Complete realm settings to apply; the path name identifies the existing realm.") Realm realm);@POST@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "createRealm", summary = "Create a new realm")- void create(@BeanParam RequestParams requestParams, @Valid Realm realm);+ @Operation(operationId = "createRealm", summary = "Create a new realm",+ description = "Creates and configures a realm in the identity provider. This operation is restricted to a super user.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Conflict+ void create(@BeanParam RequestParams requestParams,+ @Valid @RequestBody(required = true, description = "Realm name, display name, activation state, and optional identity-provider settings.") Realm realm);@DELETE@Path("{name}")@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "deleteRealm", summary = "Delete a realm")- void delete(@BeanParam RequestParams requestParams, @PathParam("name") String realm);+ @Operation(operationId = "deleteRealm", summary = "Delete a realm",+ description = "Permanently deletes a realm from the identity provider. The master realm cannot be deleted; related Manager data is not automatically removed.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.Authenticated+ @OpenApiResponses.NotFound+ @ApiResponse(responseCode = "405", description = "The master realm cannot be deleted")+ void delete(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("name") String realm);}diff --git a/model/src/main/java/org/openremote/model/security/User.java b/model/src/main/java/org/openremote/model/security/User.javaindex 71f47cb8f..2af966c5c 100644--- a/model/src/main/java/org/openremote/model/security/User.java+++ b/model/src/main/java/org/openremote/model/security/User.java@@ -22,6 +22,7 @@ package org.openremote.model.security;import com.fasterxml.jackson.annotation.JsonIgnore;import com.fasterxml.jackson.annotation.JsonProperty;import com.fasterxml.jackson.annotation.JsonSetter;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.persistence.*;import jakarta.validation.constraints.Email;import jakarta.validation.constraints.Pattern;@@ -44,6 +45,7 @@ import java.util.stream.Collectors;// TODO: Add user roles as a transient property@Entity@Subselect("select * from PUBLIC.USER_ENTITY") // Map this immutable to an SQL view, don't use/create table+@Schema(description = "Identity-provider user or service account. Administrative fields may be omitted according to caller permissions.")public class User {public static final String SERVICE_ACCOUNT_PREFIX = "service-account-";public static final String SYSTEM_ACCOUNT_ATTRIBUTE = "systemAccount";@@ -54,40 +56,51 @@ public class User {protected static Field[] propertyFields;@Formula("(select r.NAME from PUBLIC.REALM r where r.ID = REALM_ID)")+ @Schema(description = "Realm name that owns the user.", example = "building")protected String realm;@Column(name = "REALM_ID")+ @Schema(description = "Identity-provider internal realm identifier.", accessMode = Schema.AccessMode.READ_ONLY)protected String realmId;@Id+ @Schema(description = "Identity-provider user identifier.", example = "2f1c17e5-72b8-4dbe-9f8d-c49e66f82e10")protected String id;@JsonIgnore@Column(name = "USERNAME")+ @Schema(description = "Unique login name within the realm.", example = "alex")protected String username;@Column(name = "FIRST_NAME")+ @Schema(description = "Given name.", example = "Alex")protected String firstName;@Column(name = "LAST_NAME")+ @Schema(description = "Family name.", example = "Morgan")protected String lastName;@Column(name = "EMAIL")+ @Schema(description = "Email address.", example = "[email protected]")protected String email;@Column(name = "ENABLED")+ @Schema(description = "Whether this identity can authenticate.", example = "true")protected Boolean enabled;@Column(name = "CREATED_TIMESTAMP")@Convert(converter = InstantEpochConverter.class)+ @Schema(description = "Identity creation time.", accessMode = Schema.AccessMode.READ_ONLY, example = "2026-01-01T00:00:00Z")protected Instant createdOn;@Formula("(SELECT C.SECRET FROM PUBLIC.CLIENT C WHERE C.ID = SERVICE_ACCOUNT_CLIENT_LINK)")+ @Schema(description = "Client secret for a service user. Returned only by operations that explicitly expose or reset it.", accessMode = Schema.AccessMode.READ_ONLY)protected String secret; // For service users@OneToMany(fetch = FetchType.EAGER)@JoinColumn(name = "USER_ID")@JsonIgnore+ @Schema(description = "Identity-provider user attributes represented as name/value collections.")protected List<UserAttribute> attributes;public User() {diff --git a/model/src/main/java/org/openremote/model/security/UserResource.java b/model/src/main/java/org/openremote/model/security/UserResource.javaindex 4afd26669..f223e5638 100644--- a/model/src/main/java/org/openremote/model/security/UserResource.java+++ b/model/src/main/java/org/openremote/model/security/UserResource.java@@ -20,22 +20,33 @@package org.openremote.model.security;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.ExampleObject;+import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.parameters.RequestBody;+import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import jakarta.annotation.security.RolesAllowed;import jakarta.validation.Valid;import jakarta.ws.rs.*;import org.openremote.model.Constants;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import org.openremote.model.query.UserQuery;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.*;+import static org.openremote.model.http.OpenApiExamples.USER_CREATE;+import static org.openremote.model.http.OpenApiExamples.USER_QUERY;/*** Manage users in realms and get info of current user.*/// TODO Relax permissions to allow regular users to maintain their own realm-@Tag(name = "User", description = "Operations on users")+@Tag(name = "User", description = "Query and manage identity-provider users, roles, credentials, locale, and live sessions")@Path("user")public interface UserResource {@GET@@ -43,40 +54,76 @@ public interface UserResource {@Produces(APPLICATION_JSON)@SuppressWarnings("unusable-by-js")@RolesAllowed(Constants.READ_ADMIN_ROLE)- @Operation(operationId = "getClientRoles", summary = "Retrieve client roles for a realm and client")- Role[] getClientRoles(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("clientId") String clientId);+ @Operation(operationId = "getClientRoles", summary = "Retrieve client roles for a realm and client",+ description = "Returns all role definitions exposed by the named identity-provider client. Realm-administrator access is required.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFound+ Role[] getClientRoles(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = CLIENT_ID, example = EXAMPLE_CLIENT_ID) @PathParam("clientId") String clientId);@PUT@Path("{realm}/roles")@Consumes(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "updateRoles", summary = "Update roles for a realm")- void updateRoles(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, Role[] roles);+ @Operation(operationId = "updateRoles", summary = "Update OpenRemote client roles for a realm",+ description = "Creates, updates, or removes role definitions for the default OpenRemote client in the requested realm.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ void updateRoles(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @RequestBody(required = true, description = "Complete desired set of OpenRemote client role definitions; omitted existing roles are removed.") Role[] roles);@PUT@Path("{realm}/{clientId}/roles")@Consumes(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "updateClientRoles", summary = "Update client roles for a realm and client")- void updateClientRoles(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, Role[] roles, @PathParam("clientId") String clientId);+ @Operation(operationId = "updateClientRoles", summary = "Update client roles for a realm and client",+ description = "Creates, updates, or removes role definitions for a named identity-provider client.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ void updateClientRoles(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @RequestBody(required = true, description = "Complete desired set of client role definitions; omitted existing roles are removed.") Role[] roles,+ @Parameter(description = CLIENT_ID, example = EXAMPLE_CLIENT_ID) @PathParam("clientId") String clientId);@POST@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@Path("query")- @Operation(operationId = "queryUsers", summary = "Query users based on criteria")- User[] query(@BeanParam RequestParams requestParams, UserQuery query);+ @Operation(operationId = "queryUsers", summary = "Query users based on criteria",+ description = "Executes a UserQuery. Non-super users are forced into their authenticated realm and cannot see system accounts; callers with read-users but not read-admin receive basic fields only.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ User[] query(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "Realm, identity, service-account, asset-link, and field-selection criteria.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = UserQuery.class),+ examples = @ExampleObject(name = "Find human users", summary = "Find human users by username in one realm", value = USER_QUERY))) UserQuery query);@GET@Path("{realm}/{userId}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getUser", summary = "Retrieve a user in a realm")- User get(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId);+ @Operation(operationId = "getUser", summary = "Retrieve a user in a realm",+ description = "Returns one user when it belongs to the requested accessible realm. Without read-admin permission, callers may retrieve only their own user.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFound+ User get(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId);@GET@Path("user")@Produces(APPLICATION_JSON)- @Operation(operationId = "getCurrentUser", summary = "Retrieve the currently authenticated user")+ @Operation(operationId = "getCurrentUser", summary = "Retrieve the currently authenticated user",+ description = "Returns the identity-provider record corresponding to the current access token.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFoundUser getCurrent(@BeanParam RequestParams requestParams);@PUT@@ -84,45 +131,85 @@ public interface UserResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "updateUser", summary = "Update a user in a realm")- User update(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @Valid User user);+ @Operation(operationId = "updateUser", summary = "Update a user in a realm",+ description = "Updates an existing identity-provider user in an administered realm. The master administrator cannot be disabled.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @ApiResponse(responseCode = "405", description = "The requested cross-realm or protected master-administrator mutation is not allowed")+ User update(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Valid @RequestBody(required = true, description = "User profile, enabled state, attributes, and identity-provider fields to update.") User user);@PUT@Path("update")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_USER_ROLE)- @Operation(operationId = "updateSelf", summary = "Update the currently authenticated user")- User updateCurrent(@BeanParam RequestParams requestParams, @Valid User user);+ @Operation(operationId = "updateSelf", summary = "Update the currently authenticated user",+ description = "Updates the caller's own profile. A supplied user ID must match the access token; role and realm administration are not provided by this endpoint.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ User updateCurrent(@BeanParam RequestParams requestParams,+ @Valid @RequestBody(required = true, description = "Editable profile fields for the currently authenticated user.") User user);@POST@Path("{realm}/users")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "createUser", summary = "Create a new user in a realm")- User create(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @Valid User user);+ @Operation(operationId = "createUser", summary = "Create a new user in a realm",+ description = "Creates an identity-provider user in a realm administered by the caller and returns the resulting user record.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.Conflict+ User create(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Valid @RequestBody(required = true, description = "New user profile; omit the id because it is assigned by the identity provider.",+ content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = User.class),+ examples = @ExampleObject(name = "Create a human user", summary = "Create an enabled user with an English locale", value = USER_CREATE))) User user);@DELETE@Path("{realm}/users/{userId}")@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "deleteUser", summary = "Delete a user from a realm")- void delete(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId);+ @Operation(operationId = "deleteUser", summary = "Delete a user from a realm",+ description = "Permanently deletes a user from an administered realm. The master-realm administrator cannot be deleted.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.NotFound+ @ApiResponse(responseCode = "405", description = "The master-realm administrator cannot be deleted")+ void delete(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId);@PUT@Path("{realm}/request-password-reset/{userId}")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "requestUserPasswordReset", summary = "Request a password reset for a user in a realm")- void requestPasswordReset(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId);+ @Operation(operationId = "requestUserPasswordReset", summary = "Request a password reset for a user in a realm",+ description = "Asks the identity provider to send or initiate its configured password-reset action for the specified user.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @ApiResponse(responseCode = "405", description = "The caller cannot mutate a user in the requested realm")+ void requestPasswordReset(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId);@PUT@Path("request-password-reset")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_USER_ROLE)- @Operation(operationId = "requestPasswordReset", summary = "Request a password reset for the currently authenticated user")+ @Operation(operationId = "requestPasswordReset", summary = "Request a password reset for the current user",+ description = "Initiates the identity provider's configured password-reset action for the caller's own account.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequestvoid requestPasswordResetCurrent(@BeanParam RequestParams requestParams);@PUT@@ -130,76 +217,152 @@ public interface UserResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "updatePassword", summary = "Update the password for a user in a realm")- void updatePassword(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId, Credential credential);+ @Operation(operationId = "updatePassword", summary = "Update the password for a user in a realm",+ description = "Replaces a user's credential in an administered realm using the supplied credential representation.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ @ApiResponse(responseCode = "405", description = "The caller cannot mutate a user in the requested realm")+ void updatePassword(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId,+ @RequestBody(required = true, description = "New credential value and whether it is temporary.") Credential credential);@PUT@Path("reset-password")@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_USER_ROLE)- @Operation(operationId = "updateOwnPassword", summary = "Update the password for the currently authenticated user")- void updatePasswordCurrent(@BeanParam RequestParams requestParams, Credential credential);+ @Operation(operationId = "updateOwnPassword", summary = "Update the current user's password",+ description = "Replaces the caller's own identity-provider credential using the supplied credential representation.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ void updatePasswordCurrent(@BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "New credential value and whether it is temporary.") Credential credential);@GET@Path("{realm}/reset-secret/{userId}")@Produces(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "resetSecret", summary = "Reset the secret for a user in a realm")- String resetSecret(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId);+ @Operation(operationId = "resetSecret", summary = "Reset the secret for a user in a realm",+ description = "Generates and returns a new client secret for a service user in an administered realm.")+ @OpenApiResponses.Ok+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ String resetSecret(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = "Service-user identifier whose client secret is regenerated.", example = EXAMPLE_USER_ID) @PathParam("userId") String userId);@GET@Path("{realm}/userRoles/{userId}/{clientId}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getUserClientRoles", summary = "Retrieve client roles for a user using a client ID in a realm")- String[] getUserClientRoles(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId, @PathParam("clientId") String clientId);+ @Operation(operationId = "getUserClientRoles", summary = "Retrieve a user's client roles",+ description = "Returns role names assigned to one user for the named client. Without read-admin permission, callers may retrieve only their own roles.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFound+ String[] getUserClientRoles(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId,+ @Parameter(description = CLIENT_ID, example = EXAMPLE_CLIENT_ID) @PathParam("clientId") String clientId);@GET@Path("{realm}/userRealmRoles/{userId}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getUserRealmRoles", summary = "Retrieve realm roles for a user in a realm")- String[] getUserRealmRoles(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId);+ @Operation(operationId = "getUserRealmRoles", summary = "Retrieve a user's realm roles",+ description = "Returns realm-level role names assigned to one user. Without read-admin permission, callers may retrieve only their own roles.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFound+ String[] getUserRealmRoles(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId);@GET@Path("userRoles/{clientId}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getCurrentUserClientRoles", summary = "Retrieve client roles for the currently authenticated user using a client ID")- String[] getCurrentUserClientRoles(@BeanParam RequestParams requestParams, @PathParam("clientId") String clientId);+ @Operation(operationId = "getCurrentUserClientRoles", summary = "Retrieve the current user's client roles",+ description = "Returns role names assigned to the caller for the named identity-provider client.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFound+ String[] getCurrentUserClientRoles(+ @BeanParam RequestParams requestParams,+ @Parameter(description = CLIENT_ID, example = EXAMPLE_CLIENT_ID) @PathParam("clientId") String clientId);@GET@Path("userRealmRoles")@Produces(APPLICATION_JSON)- @Operation(operationId = "getCurrentUserRealmRoles", summary = "Retrieve realm roles for the currently authenticated user")+ @Operation(operationId = "getCurrentUserRealmRoles", summary = "Retrieve the current user's realm roles",+ description = "Returns realm-level role names assigned to the caller.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFoundString[] getCurrentUserRealmRoles(@BeanParam RequestParams requestParams);@PUT@Path("{realm}/userRoles/{userId}/{clientId}")@Consumes(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "updateUserClientRoles", summary = "Update client roles for a user in a realm using a client ID")- void updateUserClientRoles(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId, String[] roles, @PathParam("clientId") String clientId);+ @Operation(operationId = "updateUserClientRoles", summary = "Update a user's client roles",+ description = "Replaces the user's assigned role names for the named client in an administered realm.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ void updateUserClientRoles(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId,+ @RequestBody(required = true, description = "Complete desired set of client-role names for this user.") String[] roles,+ @Parameter(description = CLIENT_ID, example = EXAMPLE_CLIENT_ID) @PathParam("clientId") String clientId);@PUT@Path("{realm}/userRealmRoles/{userId}")@Consumes(APPLICATION_JSON)@RolesAllowed(Constants.WRITE_ADMIN_ROLE)- @Operation(operationId = "updateUserRealmRoles", summary = "Update realm roles for a user in a realm")- void updateUserRealmRoles(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId, String[] roles);+ @Operation(operationId = "updateUserRealmRoles", summary = "Update a user's realm roles",+ description = "Replaces the user's assigned realm-level role names in an administered realm.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ void updateUserRealmRoles(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId,+ @RequestBody(required = true, description = "Complete desired set of realm-role names for this user.") String[] roles);@PUT@Path("locale")@Consumes(APPLICATION_JSON)- @Operation(operationId = "updateCurrentUserLocale", summary = "Update locale for the current user in a realm")- void updateCurrentUserLocale(@BeanParam RequestParams requestParams, String locale);+ @Operation(operationId = "updateCurrentUserLocale", summary = "Update the current user's locale",+ description = "Stores the supplied non-empty locale string as the caller's identity-provider locale attribute.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ @OpenApiResponses.NotFound+ void updateCurrentUserLocale(+ @BeanParam RequestParams requestParams,+ @RequestBody(required = true, description = "BCP 47 locale identifier for the current user, encoded as a JSON string.") String locale);@GET@Path("{realm}/userSessions/{userId}")@Produces(APPLICATION_JSON)- @Operation(operationId = "getUserSessions", summary = "Retrieve sessions for a user in a realm")- UserSession[] getUserSessions(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId);+ @Operation(operationId = "getUserSessions", summary = "Retrieve live sessions for a user",+ description = "Returns active MQTT sessions for one user, including connection ID, creation time, and remote address. Without read-admin permission, callers may inspect only themselves.")+ @OpenApiResponses.Ok+ @OpenApiResponses.NotFound+ UserSession[] getUserSessions(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = USER_ID, example = EXAMPLE_USER_ID) @PathParam("userId") String userId);@GET@Path("{realm}/disconnect/{sessionID}")- @Operation(operationId = "disconnectUserSession", summary = "Disconnect a user session using a session ID")- void disconnectUserSession(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("sessionID") String sessionID);+ @Operation(operationId = "disconnectUserSession", summary = "Disconnect a user session",+ description = "Terminates the active MQTT connection identified by sessionID.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.NotFound+ void disconnectUserSession(+ @BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM) @PathParam("realm") String realm,+ @Parameter(description = "Active MQTT connection identifier returned by getUserSessions.", example = "mqtt-connection-7") @PathParam("sessionID") String sessionID);}diff --git a/model/src/main/java/org/openremote/model/services/ExternalService.java b/model/src/main/java/org/openremote/model/services/ExternalService.javaindex cb6c55b88..04ffd501b 100644--- a/model/src/main/java/org/openremote/model/services/ExternalService.java+++ b/model/src/main/java/org/openremote/model/services/ExternalService.java@@ -21,6 +21,7 @@ package org.openremote.model.services;import com.fasterxml.jackson.annotation.JsonIgnore;import com.fasterxml.jackson.annotation.JsonProperty;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.validation.constraints.NotEmpty;import jakarta.validation.constraints.NotNull;@@ -34,6 +35,7 @@ import jakarta.validation.constraints.Size;* to register, manage,* and track the lifecycle of external services within the OpenRemote system.*/+@Schema(description = "Leased external-service registration advertised through the OpenRemote Manager.")public class ExternalService {/**@@ -45,6 +47,7 @@ public class ExternalService {@Size(min = 3, max = 255, message = "{ExternalService.serviceId.Size}")@NotEmpty(message = "{ExternalService.serviceId.NotEmpty}")@JsonProperty("serviceId")+ @Schema(description = "Stable identifier shared by all instances of the same service.", example = "energy-service")protected String serviceId;/**@@ -55,6 +58,7 @@ public class ExternalService {* registry when the service is registered.*/@JsonProperty(value = "instanceId")+ @Schema(description = "Instance number assigned by the Manager during registration.", accessMode = Schema.AccessMode.READ_ONLY, example = "1")protected int instanceId;/**@@ -65,6 +69,7 @@ public class ExternalService {*/@Size(min = 3, max = 255, message = "{ExternalService.version.Size}")@JsonProperty("version")+ @Schema(description = "Service implementation version.", example = "1.4.0")protected String version;/**@@ -75,6 +80,7 @@ public class ExternalService {* across all realms if the isGlobal flag is also set to true.*/@JsonProperty(access = JsonProperty.Access.READ_ONLY)+ @Schema(description = "Realm that owns this registration.", accessMode = Schema.AccessMode.READ_ONLY, example = "building")protected String realm;/**@@ -86,6 +92,7 @@ public class ExternalService {* Should be a valid icon name from the Material Design Icons library.*/@JsonProperty("icon")+ @Schema(description = "Material Design Icons name used by Manager UIs.", example = "puzzle")protected String icon = "puzzle";/**@@ -97,6 +104,7 @@ public class ExternalService {@NotEmpty(message = "{ExternalService.label.NotEmpty}")@Size(min = 1, max = 255, message = "{ExternalService.label.Size}")@JsonProperty("label")+ @Schema(description = "Human-readable service label.", example = "Energy Service")protected String label;/**@@ -110,6 +118,7 @@ public class ExternalService {@Size(min = 3, max = 512, message = "{ExternalService.homepageUrl.Size}")@NotEmpty(message = "{ExternalService.homepageUrl.NotEmpty}")@JsonProperty("homepageUrl")+ @Schema(description = "Absolute URL of the service UI or configuration page.", example = "https://services.example.com/energy")protected String homepageUrl;/**@@ -120,6 +129,7 @@ public class ExternalService {*/@NotNull(message = "{ExternalService.status.NotNull}")@JsonProperty("status")+ @Schema(description = "Current availability derived from the registration lease.")protected ExternalServiceStatus status;/**@@ -142,6 +152,7 @@ public class ExternalService {* registered by a super admin service user and set to MASTER_REALM.*/@JsonProperty(access = JsonProperty.Access.READ_ONLY)+ @Schema(description = "Whether the service is visible to every realm.", accessMode = Schema.AccessMode.READ_ONLY)protected boolean isGlobal = false;public ExternalService() {diff --git a/model/src/main/java/org/openremote/model/services/ExternalServiceResource.java b/model/src/main/java/org/openremote/model/services/ExternalServiceResource.javaindex aa91b05ed..072a0d11a 100644--- a/model/src/main/java/org/openremote/model/services/ExternalServiceResource.java+++ b/model/src/main/java/org/openremote/model/services/ExternalServiceResource.java@@ -20,12 +20,15 @@package org.openremote.model.services;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;import io.swagger.v3.oas.annotations.media.Content;import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.parameters.RequestBody;import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.Constants;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.annotation.security.RolesAllowed;@@ -35,6 +38,8 @@ import jakarta.validation.constraints.Size;import jakarta.ws.rs.*;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;+import static org.openremote.model.http.OpenApiDescriptions.EXAMPLE_REALM;+import static org.openremote.model.http.OpenApiDescriptions.REALM;/*** REST resource for managing external services.@@ -45,8 +50,9 @@ import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;* Registered services are made available via the OpenRemote manager's Web UI* and API, enabling centralized service management and monitoring.*/-@Tag(name = "Services", description = "Registration and management of external services")+@Tag(name = "Services", description = "Register, discover, renew, and deregister leased external-service instances")@Path("service")public interface ExternalServiceResource {/**@@ -64,13 +70,15 @@ public interface ExternalServiceResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({ Constants.WRITE_SERVICES_ROLE })- @Operation(operationId = "registerService", summary = "Register an external service with the OpenRemote manager", responses = {+ @Operation(operationId = "registerService", summary = "Register an external service with the OpenRemote Manager",+ description = "Registers a realm-scoped service instance for the request realm. The caller must be a service account; the returned object contains the assigned instance ID and initial lease state.", responses = {@ApiResponse(responseCode = "200", description = "Service registered successfully", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExternalService.class))),@ApiResponse(responseCode = "400", description = "Invalid external service object"),@ApiResponse(responseCode = "409", description = "ExternalService instance already registered"),})ExternalService registerService(@BeanParam RequestParams requestParams,- @NotNull @Valid ExternalService service);+ @NotNull @Valid @RequestBody(required = true,+ description = "Realm-scoped service metadata and lease settings; instanceId is assigned by the Manager.") ExternalService service);/*** Register a new global external service with the OpenRemote@@ -87,13 +95,15 @@ public interface ExternalServiceResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({ Constants.WRITE_SERVICES_ROLE })- @Operation(operationId = "registerGlobalService", summary = "Register a global external service with the OpenRemote manager", responses = {+ @Operation(operationId = "registerGlobalService", summary = "Register a global external service with the OpenRemote Manager",+ description = "Registers a service visible in every realm. The caller must be a super-user service account and the request must use the master realm.", responses = {@ApiResponse(responseCode = "200", description = "Service registered successfully", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExternalService.class))),@ApiResponse(responseCode = "400", description = "Invalid external service object"),@ApiResponse(responseCode = "409", description = "ExternalService instance already registered"),})ExternalService registerGlobalService(@BeanParam RequestParams requestParams,- @NotNull @Valid ExternalService service);+ @NotNull @Valid @RequestBody(required = true,+ description = "Globally visible service metadata and lease settings; instanceId is assigned by the Manager.") ExternalService service);/*** Retrieve all registered external services for a specific@@ -105,10 +115,13 @@ public interface ExternalServiceResource {@GET@Produces(APPLICATION_JSON)@RolesAllowed({ Constants.READ_SERVICES_ROLE })- @Operation(operationId = "getServices", summary = "List all registered external services for the given realm within the OpenRemote manager", responses = {+ @Operation(operationId = "getServices", summary = "List registered external services for a realm",+ description = "Returns all active realm-scoped service registrations for an active realm accessible to the caller.", responses = {@ApiResponse(responseCode = "200", description = "List of registered external services", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExternalService[].class))),})- ExternalService[] getServices(@BeanParam RequestParams requestParams, @QueryParam("realm") @NotNull String realm);+ @OpenApiResponses.BadRequest+ ExternalService[] getServices(@BeanParam RequestParams requestParams,+ @Parameter(description = REALM, example = EXAMPLE_REALM, required = true) @QueryParam("realm") @NotNull String realm);/*** Retrieve a specific external service by its serviceId and@@ -122,13 +135,15 @@ public interface ExternalServiceResource {@Path("{serviceId}/{instanceId}")@Produces(APPLICATION_JSON)@RolesAllowed({ Constants.READ_SERVICES_ROLE })- @Operation(operationId = "getService", summary = "Retrieve a specific external service by its serviceId and instanceId", responses = {+ @Operation(operationId = "getService", summary = "Retrieve an external service instance",+ description = "Returns one registered instance by stable service ID and numeric instance ID, after verifying access to the service's realm.", responses = {@ApiResponse(responseCode = "200", description = "ExternalService retrieved successfully", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExternalService.class))),@ApiResponse(responseCode = "404", description = "ExternalService not found"),})+ @OpenApiResponses.BadRequestExternalService getService(@BeanParam RequestParams requestParams,- @PathParam("serviceId") @NotNull @Size(min = 1) String serviceId,- @PathParam("instanceId") int instanceId);+ @Parameter(description = "Stable service type identifier chosen by the service.", example = "weather") @PathParam("serviceId") @NotNull @Size(min = 1) String serviceId,+ @Parameter(description = "Numeric instance identifier assigned during registration.", example = "1") @PathParam("instanceId") int instanceId);/*** Retrieve all external services that are globally registered@@ -139,7 +154,8 @@ public interface ExternalServiceResource {@Path("global")@Produces(APPLICATION_JSON)@RolesAllowed({ Constants.READ_SERVICES_ROLE })- @Operation(operationId = "getGlobalServices", summary = "List all registered external services that are globally accessible within the OpenRemote manager", responses = {+ @Operation(operationId = "getGlobalServices", summary = "List globally available external services",+ description = "Returns active registrations marked as globally available across realms.", responses = {@ApiResponse(responseCode = "200", description = "List of registered external services", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExternalService[].class))),})ExternalService[] getGlobalServices(@BeanParam RequestParams requestParams);@@ -157,13 +173,15 @@ public interface ExternalServiceResource {@PUT@Path("{serviceId}/{instanceId}")@RolesAllowed({ Constants.WRITE_SERVICES_ROLE })- @Operation(operationId = "heartbeat", summary = "Update the active registration lease for the specified external service", responses = {+ @Operation(operationId = "heartbeat", summary = "Renew an external service registration lease",+ description = "Extends the lease of one service instance. The caller must be the service account that registered it; global-service heartbeats additionally require a super user.", responses = {@ApiResponse(responseCode = "204", description = "Heartbeat sent successfully"),@ApiResponse(responseCode = "404", description = "Service instance not found"),})+ @OpenApiResponses.BadRequestvoid heartbeat(@BeanParam RequestParams requestParams,- @PathParam("serviceId") @NotNull @Size(min = 1) String serviceId,- @PathParam("instanceId") int instanceId);+ @Parameter(description = "Stable service type identifier chosen by the service.", example = "weather") @PathParam("serviceId") @NotNull @Size(min = 1) String serviceId,+ @Parameter(description = "Numeric instance identifier assigned during registration.", example = "1") @PathParam("instanceId") int instanceId);/*** Deregister an external service from the registry.@@ -178,11 +196,13 @@ public interface ExternalServiceResource {@DELETE@Path("{serviceId}/{instanceId}")@RolesAllowed({ Constants.WRITE_SERVICES_ROLE })- @Operation(operationId = "deregisterService", summary = "Deregister an external service", responses = {+ @Operation(operationId = "deregisterService", summary = "Deregister an external service",+ description = "Removes an active service registration. The caller must be the service account that registered it; global-service removal additionally requires a super user.", responses = {@ApiResponse(responseCode = "204", description = "Service deregistered successfully"),@ApiResponse(responseCode = "404", description = "Service instance not found"),})- void deregisterService(@BeanParam RequestParams requestParams, @PathParam("serviceId") String serviceId,- @PathParam("instanceId") int instanceId);+ void deregisterService(@BeanParam RequestParams requestParams,+ @Parameter(description = "Stable service type identifier chosen by the service.", example = "weather") @PathParam("serviceId") String serviceId,+ @Parameter(description = "Numeric instance identifier assigned during registration.", example = "1") @PathParam("instanceId") int instanceId);}diff --git a/model/src/main/java/org/openremote/model/syslog/SyslogEvent.java b/model/src/main/java/org/openremote/model/syslog/SyslogEvent.javaindex 5bf27d03b..863e645a6 100644--- a/model/src/main/java/org/openremote/model/syslog/SyslogEvent.java+++ b/model/src/main/java/org/openremote/model/syslog/SyslogEvent.java@@ -19,6 +19,7 @@*/package org.openremote.model.syslog;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.persistence.*;import jakarta.validation.constraints.NotNull;import org.openremote.model.event.shared.EventFilter;@@ -30,6 +31,7 @@ import static org.openremote.model.Constants.PERSISTENCE_SEQUENCE_ID_GENERATOR;@Entity@Table(name = "SYSLOG_EVENT")+@Schema(description = "Persisted Manager log event with Unix-millisecond timestamp, severity, category, optional subcategory, and message.")public class SyslogEvent extends SharedEvent {static public class LevelCategoryFilter implements EventFilter<SyslogEvent> {@@ -83,22 +85,27 @@ public class SyslogEvent extends SharedEvent {@Column(name = "ID")@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = PERSISTENCE_SEQUENCE_ID_GENERATOR)@SequenceGenerator(name = PERSISTENCE_SEQUENCE_ID_GENERATOR, initialValue = 1000, allocationSize = 1)+ @Schema(description = "Server-assigned numeric event identifier.", accessMode = Schema.AccessMode.READ_ONLY)protected Long id;@NotNull@Enumerated(EnumType.ORDINAL)@Column(name = "LEVEL", nullable = false)+ @Schema(description = "Log severity.")protected SyslogLevel level;@NotNull@Enumerated(EnumType.STRING)@Column(name = "CATEGORY", nullable = false)+ @Schema(description = "High-level Manager subsystem category.")protected SyslogCategory category;@Column(name = "SUBCATEGORY", length = 1024)+ @Schema(description = "Optional component, logger, or class within the category.", example = "org.openremote.manager.asset")protected String subCategory;@Column(name = "MESSAGE", length = 131072)+ @Schema(description = "Rendered log message.")protected String message;protected SyslogEvent() {diff --git a/model/src/main/java/org/openremote/model/syslog/SyslogResource.java b/model/src/main/java/org/openremote/model/syslog/SyslogResource.javaindex 948cb28b8..6f320d782 100644--- a/model/src/main/java/org/openremote/model/syslog/SyslogResource.java+++ b/model/src/main/java/org/openremote/model/syslog/SyslogResource.java@@ -20,8 +20,18 @@package org.openremote.model.syslog;import io.swagger.v3.oas.annotations.Operation;+import io.swagger.v3.oas.annotations.Parameter;+import io.swagger.v3.oas.annotations.enums.Explode;+import io.swagger.v3.oas.annotations.enums.ParameterStyle;+import io.swagger.v3.oas.annotations.headers.Header;+import io.swagger.v3.oas.annotations.media.ArraySchema;+import io.swagger.v3.oas.annotations.media.Content;+import io.swagger.v3.oas.annotations.media.Schema;+import io.swagger.v3.oas.annotations.responses.ApiResponse;+import io.swagger.v3.oas.annotations.parameters.RequestBody;import io.swagger.v3.oas.annotations.tags.Tag;import org.openremote.model.Constants;+import org.openremote.model.http.OpenApiResponses;import org.openremote.model.http.RequestParams;import jakarta.annotation.security.RolesAllowed;import jakarta.validation.Valid;@@ -31,22 +41,38 @@ import java.util.List;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;-@Tag(name = "Syslog", description = "Operations on syslog events")+@Tag(name = "Syslog", description = "Query and clear stored Manager logs and maintain syslog storage settings")@Path("syslog")public interface SyslogResource {@GET@Path("event")@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_LOGS_ROLE})- @Operation(operationId = "getEvents", summary = "Retrieve the syslog events")+ @Operation(operationId = "getEvents", summary = "Retrieve stored syslog events",+ description = "Returns a page of log events filtered by severity, Unix-millisecond time range, categories, and subcategories. RFC 8288 Link headers point to the next and last pages.")+ @ApiResponse(responseCode = "200", description = "The requested page of syslog events",+ headers = @Header(name = "Link", description = "RFC 8288 pagination links for the next and last pages", schema = @Schema(type = "string")),+ content = @Content(mediaType = APPLICATION_JSON, array = @ArraySchema(schema = @Schema(implementation = SyslogEvent.class))))+ @OpenApiResponses.BadRequest@SuppressWarnings({"unusable-by-js"})- Response getEvents(@BeanParam RequestParams requestParams, @QueryParam("level") SyslogLevel level, @QueryParam("per_page") Integer perPage, @QueryParam("page") Integer page, @QueryParam("from") Long from, @QueryParam("to") Long to, @QueryParam("category") List<SyslogCategory> categories, @QueryParam("subCategory") List<String> subCategories);+ Response getEvents(+ @BeanParam RequestParams requestParams,+ @Parameter(description = "Minimum log severity to return.", example = "INFO") @QueryParam("level") SyslogLevel level,+ @Parameter(description = "Maximum number of events per page.", example = "100") @QueryParam("per_page") Integer perPage,+ @Parameter(description = "One-based result page number.", example = "1") @QueryParam("page") Integer page,+ @Parameter(description = "Inclusive lower bound for event timestamps, in Unix milliseconds.", example = "1767225600000") @QueryParam("from") Long from,+ @Parameter(description = "Exclusive upper bound for event timestamps, in Unix milliseconds.", example = "1767312000000") @QueryParam("to") Long to,+ @Parameter(description = "Log categories to include; repeat the query parameter for multiple values.", style = ParameterStyle.FORM, explode = Explode.TRUE) @QueryParam("category") List<SyslogCategory> categories,+ @Parameter(description = "Log subcategories to include; repeat the query parameter for multiple values.", style = ParameterStyle.FORM, explode = Explode.TRUE, example = "org.openremote.manager.asset") @QueryParam("subCategory") List<String> subCategories);@DELETE@Path("event")@RolesAllowed({Constants.WRITE_ADMIN_ROLE})- @Operation(operationId = "clearEvents", summary = "Clear the syslog events")+ @Operation(operationId = "clearEvents", summary = "Clear stored syslog events",+ description = "Permanently removes all events from the configured syslog storage.")+ @OpenApiResponses.NoContentvoid clearEvents(@BeanParam RequestParams requestParams);@GET@@ -54,13 +80,19 @@ public interface SyslogResource {@Consumes(APPLICATION_JSON)@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ADMIN_ROLE})- @Operation(operationId = "getConfig", summary = "Retrieve the syslog configuration")+ @Operation(operationId = "getConfig", summary = "Retrieve the syslog configuration",+ description = "Returns the current log-storage and retention configuration.")+ @OpenApiResponses.OkSyslogConfig getConfig(@BeanParam RequestParams requestParams);@PUT@Path("config")@Consumes(APPLICATION_JSON)@RolesAllowed({Constants.WRITE_ADMIN_ROLE})- @Operation(operationId = "updateConfig", summary = "Update the syslog configuration")- void updateConfig(@BeanParam RequestParams requestParams, @Valid SyslogConfig config);+ @Operation(operationId = "updateConfig", summary = "Update the syslog configuration",+ description = "Validates and applies log-storage and retention settings.")+ @OpenApiResponses.NoContent+ @OpenApiResponses.BadRequest+ void updateConfig(@BeanParam RequestParams requestParams,+ @Valid @RequestBody(required = true, description = "Log level, storage, and retention settings to apply.") SyslogConfig config);}diff --git a/model/src/main/java/org/openremote/model/system/StatusResource.java b/model/src/main/java/org/openremote/model/system/StatusResource.javaindex 7aba0c0cb..a1c29aaca 100644--- a/model/src/main/java/org/openremote/model/system/StatusResource.java+++ b/model/src/main/java/org/openremote/model/system/StatusResource.java@@ -26,12 +26,13 @@ import jakarta.ws.rs.GET;import jakarta.ws.rs.Path;import jakarta.ws.rs.Produces;import org.openremote.model.Constants;+import org.openremote.model.http.OpenApiResponses;import java.util.Map;import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;-@Tag(name = "Status", description = "Operations on system status")+@Tag(name = "Status", description = "Read Manager health and build information")@Path("")public interface StatusResource {@@ -40,12 +41,17 @@ public interface StatusResource {@GET@Produces(APPLICATION_JSON)@RolesAllowed({Constants.READ_ADMIN_ROLE})- @Operation(operationId = "getHealthStatus", summary = "Retrieve the health status of the system")+ @Operation(operationId = "getHealthStatus", summary = "Retrieve the health status of the system",+ description = "Returns health data keyed by registered health-provider name. A null provider result is represented as JSON null.")+ @OpenApiResponses.Ok+ @OpenApiResponses.AuthenticatedMap<String, Object> getHealthStatus();@Path("info")@GET@Produces(APPLICATION_JSON)- @Operation(operationId = "getInfo", summary = "Retrieve the system information")+ @Operation(operationId = "getInfo", summary = "Retrieve the system information",+ description = "Returns public bootstrap information, including the Manager version and identity-provider URL.")+ @OpenApiResponses.OkMap<String, Object> getInfo();}diff --git a/model/src/main/java/org/openremote/model/value/AbstractNameValueHolder.java b/model/src/main/java/org/openremote/model/value/AbstractNameValueHolder.javaindex 21511481f..669d8fc43 100644--- a/model/src/main/java/org/openremote/model/value/AbstractNameValueHolder.java+++ b/model/src/main/java/org/openremote/model/value/AbstractNameValueHolder.java@@ -22,6 +22,7 @@ package org.openremote.model.value;import com.fasterxml.jackson.annotation.JsonIgnore;import com.fasterxml.jackson.annotation.JsonProperty;import com.fasterxml.jackson.databind.annotation.JsonSerialize;+import io.swagger.v3.oas.annotations.media.Schema;import jakarta.annotation.Nonnull;import jakarta.annotation.Nullable;import jakarta.validation.Valid;@@ -36,14 +37,17 @@ import java.util.Optional;public abstract class AbstractNameValueHolder<T> implements NameValueHolder<T>, Serializable {@JsonIgnore+ @Schema(description = "OpenRemote value type name used to interpret and validate value.", example = "number")protected ValueDescriptor<T> type;@JsonProperty(access = JsonProperty.Access.WRITE_ONLY)@Valid+ @Schema(description = "Typed JSON value; its shape is determined by type and may be null.", nullable = true)protected T value;@JsonIgnoreprotected String valueStr; // This is for lazy value initialisation when deserialising@NotBlank(message = "{Asset.valueHolder.name.NotBlank}")@Pattern(regexp = "^\\w+$")+ @Schema(description = "Machine-readable name.", example = "temperature")protected String name;protected AbstractNameValueHolder() {