Enhancements and corrections in openapi spec (#5203)

- 'config' in RootUIComponent/UIComponent was of the wrong type in openapi spec - getType accessor in UIComponent generated a property - Updated the naming of data structures in openapi spec w/o the internal DTO nomenclature for consistency and simplicity Also-by: Florian Hotze <dev@florianhotze.com> Also-by: Wouter Born <github@maindrain.net> Signed-off-by: Jeff James <jeff@james-online.com>
2026-07-29 12:34:22 +02:00 · 2026-01-22 14:49:20 +01:00
parent aff119cd19
commit fbd0d987ea
74 changed files with 412 additions and 48 deletions
@@ -273,13 +273,16 @@ public class ThingActionsResource implements RESTResource {
        return scopeAnnotation.name();
    }

+    @Schema(name = "ThingAction")
    private static class ThingActionDTO {
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
        public String actionUid = "";

        public @Nullable String label;
        public @Nullable String description;
        public @Nullable Visibility visibility;

+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
        public List<Input> inputs = new ArrayList<>();

        public @Nullable List<ConfigDescriptionParameterDTO> inputConfigDescriptions;
@@ -15,13 +15,17 @@ package org.openhab.core.automation.rest.internal.dto;
 import org.openhab.core.automation.RuleStatusInfo;
 import org.openhab.core.automation.dto.RuleDTO;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize rules with dynamic data like the status.
 *
 * @author Kai Kreuzer - Initial contribution
 */
+@Schema(name = "EnrichedRule")
 public class EnrichedRuleDTO extends RuleDTO {

    public RuleStatusInfo status;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Boolean editable;
 }
@@ -14,12 +14,16 @@ package org.openhab.core.automation.dto;

 import java.util.Map;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize the respective class.
 *
 * @author Markus Rathgeb - Initial contribution
 */
+@Schema(name = "Action")
 public class ActionDTO extends ModuleDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Map<String, String> inputs;
 }
@@ -14,12 +14,16 @@ package org.openhab.core.automation.dto;

 import java.util.Map;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize the respective class.
 *
 * @author Markus Rathgeb - Initial contribution
 */
+@Schema(name = "Condition")
 public class ConditionDTO extends ModuleDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Map<String, String> inputs;
 }
@@ -14,16 +14,22 @@ package org.openhab.core.automation.dto;

 import java.util.Map;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize the respective class.
 *
 * @author Markus Rathgeb - Initial contribution
 */
+@Schema(name = "Module")
 public class ModuleDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String id;
    public String label;
    public String description;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Map<String, Object> configuration;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String type;
 }
@@ -18,17 +18,24 @@ import java.util.Set;
 import org.openhab.core.automation.Visibility;
 import org.openhab.core.config.core.dto.ConfigDescriptionParameterDTO;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize the respective class.
 *
 * @author Markus Rathgeb - Initial contribution
 */
+@Schema(name = "ModuleType")
 public class ModuleTypeDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String uid;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Visibility visibility;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Set<String> tags;
    public String label;
    public String description;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<ConfigDescriptionParameterDTO> configDescriptions;
 }
@@ -20,23 +20,35 @@ import org.eclipse.jdt.annotation.NonNull;
 import org.openhab.core.automation.Visibility;
 import org.openhab.core.config.core.dto.ConfigDescriptionParameterDTO;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize rules.
 *
 * @author Markus Rathgeb - Initial contribution
 */
+@Schema(name = "Rule")
 public class RuleDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<@NonNull TriggerDTO> triggers;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<@NonNull ConditionDTO> conditions;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<@NonNull ActionDTO> actions;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Map<@NonNull String, @NonNull Object> configuration;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<@NonNull ConfigDescriptionParameterDTO> configDescriptions;
    public String templateUID;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String templateState;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String uid;
    public String name;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Set<@NonNull String> tags;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Visibility visibility;
    public String description;
 }
@@ -12,11 +12,14 @@
 */
 package org.openhab.core.automation.dto;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize the respective class.
 *
 * @author Markus Rathgeb - Initial contribution
 */
+@Schema(name = "Trigger")
 public class TriggerDTO extends ModuleDTO {

 }
@@ -29,7 +29,6 @@ import org.eclipse.jdt.annotation.Nullable;
 */
@NonNullByDefault
 public class ConfigDescriptionParameterGroup {
-
    private final String name;
    private final @Nullable String context;
    private final boolean advanced;
@@ -16,17 +16,20 @@ import java.util.List;

 import org.openhab.core.config.core.ConfigDescription;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * {@link ConfigDescriptionDTO} is a data transfer object for {@link ConfigDescription}.
 *
 * @author Dennis Nobel - Initial contribution
 */
+@Schema(name = "ConfigDescription")
 public class ConfigDescriptionDTO {

    public String uri;
-
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<ConfigDescriptionParameterDTO> parameters;
-
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<ConfigDescriptionParameterGroupDTO> parameterGroups;

    public ConfigDescriptionDTO() {
@@ -19,6 +19,8 @@ import org.openhab.core.config.core.ConfigDescriptionParameter.Type;

 import com.google.gson.annotations.SerializedName;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize parameter of a configuration description.
 *
@@ -27,6 +29,7 @@ import com.google.gson.annotations.SerializedName;
 * @author Chris Jackson - Added group, advanced, limitToOptions, multipleLimit, verify attributes
 * @author Thomas Höfer - Added unit
 */
+@Schema(name = "ConfigDescriptionParameter")
 public class ConfigDescriptionParameterDTO {

    public String context;
@@ -34,8 +37,10 @@ public class ConfigDescriptionParameterDTO {
    public String defaultValue;
    public String description;
    public String label;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String name;
    public boolean required;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Type type;
    public BigDecimal min;
    public BigDecimal max;
@@ -12,16 +12,21 @@
 */
 package org.openhab.core.config.core.dto;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize options of a
 * parameter group.
 *
 * @author Chris Jackson - Initial contribution
 */
+@Schema(name = "ConfigDescriptionParameterGroup")
 public class ConfigDescriptionParameterGroupDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String name;
    public String context;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Boolean advanced;
    public String label;
    public String description;
@@ -12,12 +12,15 @@
 */
 package org.openhab.core.config.core.dto;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize filter criteria of a
 * parameter.
 *
 * @author Alex Tugarev - Initial contribution
 */
+@Schema(name = "FilterCriteria")
 public class FilterCriteriaDTO {

    public String value;
@@ -12,12 +12,15 @@
 */
 package org.openhab.core.config.core.dto;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize options of a
 * parameter.
 *
 * @author Alex Tugarev - Initial contribution
 */
+@Schema(name = "ParameterOption")
 public class ParameterOptionDTO {

    public String label;
@@ -1,4 +0,0 @@
-Bundle-SymbolicName: ${project.artifactId}
-Import-Package: \
-  org.jupnp.*;resolution:=optional,\
-  *
@@ -18,24 +18,33 @@ import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.core.config.discovery.DiscoveryResultFlag;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize discovery results.
 *
 * @author Dennis Nobel - Initial contribution
 * @author Thomas Höfer - Added representation
 */
+@Schema(name = "DiscoveryResult")
@NonNullByDefault
 public class DiscoveryResultDTO {

    public @Nullable String bridgeUID;
-    public @Nullable DiscoveryResultFlag flag;
-    public @Nullable String label;
-    public @Nullable Map<String, Object> properties;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    public DiscoveryResultFlag flag;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    public String label;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
+    public Map<String, Object> properties;
    public @Nullable String representationProperty;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public @NonNullByDefault({}) String thingUID;
    public @Nullable String thingTypeUID;

+    // do not remove - needed by GSON
    public DiscoveryResultDTO() {
+        this("", null, null, "", DiscoveryResultFlag.NEW, Map.of(), null);
    }

    public DiscoveryResultDTO(String thingUID, @Nullable String bridgeUID, @Nullable String thingTypeUID, String label,
@@ -16,13 +16,17 @@ import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.core.audio.AudioSink;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * A DTO that is used on the REST API to provide infos about {@link AudioSink} to UIs.
 *
 * @author Laurent Garnier - Initial contribution
 */
+@Schema(name = "AudioSink")
@NonNullByDefault
 public class AudioSinkDTO {
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String id;
    public @Nullable String label;

@@ -16,13 +16,17 @@ import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.core.audio.AudioSource;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * A DTO that is used on the REST API to provide infos about {@link AudioSource} to UIs.
 *
 * @author Laurent Garnier - Initial contribution
 */
+@Schema(name = "AudioSource")
@NonNullByDefault
 public class AudioSourceDTO {
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String id;
    public @Nullable String label;

@@ -14,6 +14,8 @@ package org.openhab.core.io.rest.auth.internal;

 import org.openhab.core.auth.User;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * A DTO object for a successful token endpoint response, as per RFC 6749, Section 5.1.
 *
@@ -22,6 +24,7 @@ import org.openhab.core.auth.User;
 *
 * @author Yannick Schaus - initial contribution
 */
+@Schema(name = "TokenResponse")
 public class TokenResponseDTO {
    public String access_token;
    public String token_type;
@@ -14,11 +14,14 @@ package org.openhab.core.io.rest.auth.internal;

 import java.util.Date;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * A DTO representing a user API token, without the sensible information.
 *
 * @author Yannick Schaus - initial contribution
 */
+@Schema(name = "UserApiToken")
 public class UserApiTokenDTO {
    public String name;
    public Date createdTime;
@@ -16,11 +16,14 @@ import java.util.Collection;

 import org.openhab.core.auth.User;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * A DTO representing a {@link User}.
 *
 * @author Yannick Schaus - initial contribution
 */
+@Schema(name = "User")
 public class UserDTO {
    public String name;
    public Collection<String> roles;
@@ -14,11 +14,14 @@ package org.openhab.core.io.rest.auth.internal;

 import java.util.Date;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * A DTO representing a user session, without the sensible information.
 *
 * @author Yannick Schaus - initial contribution
 */
+@Schema(name = "UserSession")
 public class UserSessionDTO {
    public String sessionId;
    public Date createdTime;
@@ -15,14 +15,18 @@ package org.openhab.core.io.rest.core.discovery;
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize the information about binding discovery.
 *
 * @author Laurent Garnier - Initial contribution
 */
+@Schema(name = "DiscoveryInfo")
@NonNullByDefault
 public class DiscoveryInfoDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public boolean inputSupported;
    public @Nullable String inputLabel;
    public @Nullable String inputDescription;
@@ -14,13 +14,17 @@ package org.openhab.core.io.rest.core.fileformat;

 import java.util.List;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object to serialize the different components that can be contained
 * in a file format (items, things, ...) including an optional list of warnings.
 *
 * @author Laurent Garnier - Initial contribution
 */
+@Schema(name = "ExtendedFileFormat")
 public class ExtendedFileFormatDTO extends FileFormatDTO {

+    @Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED)
    public List<String> warnings;
 }
@@ -14,17 +14,25 @@ package org.openhab.core.io.rest.core.fileformat;

 import java.util.Map;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object to serialize a channel link for an item contained in a file format.
 *
 * @author Laurent Garnier - Initial contribution
 */
+@Schema(name = "FileFormatChannelLink")
+@NonNullByDefault
 public class FileFormatChannelLinkDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String channelUID;
-    public Map<String, Object> configuration;
+    public @Nullable Map<String, Object> configuration;

-    public FileFormatChannelLinkDTO(String channelUID, Map<String, Object> configuration) {
+    public FileFormatChannelLinkDTO(String channelUID, @Nullable Map<String, Object> configuration) {
        this.channelUID = channelUID;
        this.configuration = configuration;
    }
@@ -16,14 +16,19 @@ import java.util.List;

 import org.openhab.core.thing.dto.ThingDTO;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object to serialize the different components that can be contained
 * in a file format (items, things, ...).
 *
 * @author Laurent Garnier - Initial contribution
 */
+@Schema(name = "FileFormat")
 public class FileFormatDTO {

+    @Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED)
    public List<FileFormatItemDTO> items;
+    @Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED)
    public List<ThingDTO> things;
 }
@@ -20,11 +20,14 @@ import org.openhab.core.items.dto.GroupItemDTO;
 import org.openhab.core.items.dto.ItemDTO;
 import org.openhab.core.items.dto.MetadataDTO;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object to serialize an item contained in a file format.
 *
 * @author Laurent Garnier - Initial contribution
 */
+@Schema(name = "FileFormatItem")
 public class FileFormatItemDTO extends ItemDTO {

    public String groupType;
@@ -250,7 +250,8 @@ public class ItemResource implements RESTResource {
    @RolesAllowed({ Role.USER, Role.ADMIN })
    @Produces(MediaType.APPLICATION_JSON)
    @Operation(operationId = "getItems", summary = "Get all available items.", responses = {
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(array = @ArraySchema(schema = @Schema(implementation = EnrichedItemDTO.class)))) })
+            @ApiResponse(responseCode = "200", description = "OK", content = @Content(array = @ArraySchema(schema = @Schema(oneOf = {
+                    EnrichedItemDTO.class, EnrichedGroupItemDTO.class })))) })
    public Response getItems(final @Context UriInfo uriInfo, final @Context HttpHeaders httpHeaders,
            @Context Request request,
            @HeaderParam(HttpHeaders.ACCEPT_LANGUAGE) @Parameter(description = "language") @Nullable String language,
@@ -16,12 +16,15 @@ import java.util.List;

 import org.openhab.core.semantics.SemanticTag;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * A DTO representing a {@link SemanticTag}.
 *
 * @author Jimmy Tanagra - initial contribution
 * @author Laurent Garnier - Class renamed and members uid, description and editable added
 */
+@Schema(name = "EnrichedSemanticTag")
 public class EnrichedSemanticTagDTO {
    public String uid;
    public String name;
@@ -17,11 +17,14 @@ import org.openhab.core.items.dto.GroupItemDTO;
 import org.openhab.core.items.dto.ItemDTO;
 import org.openhab.core.types.StateDescription;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is an enriched data transfer object that is used to serialize group items.
 *
 * @author Dennis Nobel - Initial contribution
 */
+@Schema(name = "EnrichedGroupItem")
 public class EnrichedGroupItemDTO extends EnrichedItemDTO {

    public EnrichedGroupItemDTO(ItemDTO itemDTO, EnrichedItemDTO[] members, String link, String state, String lastState,
@@ -18,6 +18,8 @@ import org.openhab.core.items.dto.ItemDTO;
 import org.openhab.core.types.CommandDescription;
 import org.openhab.core.types.StateDescription;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is an enriched data transfer object that is used to serialize items with dynamic data like the state, the state
 * description and the link.
@@ -27,9 +29,11 @@ import org.openhab.core.types.StateDescription;
 * @author Mark Herwege - Added default unit symbol
 * @author Mark Herwege - Added parent groups
 */
+@Schema(name = "EnrichedItem")
 public class EnrichedItemDTO extends ItemDTO {

    public String link;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String state;
    public String transformedState;
    public StateDescription stateDescription;
@@ -40,6 +44,7 @@ public class EnrichedItemDTO extends ItemDTO {
    public String unitSymbol;
    public Map<String, Object> metadata;
    public EnrichedItemDTO[] parents = null;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Boolean editable;

    public EnrichedItemDTO(ItemDTO itemDTO, String link, String state, String lastState, Long lastStateUpdate,
@@ -12,13 +12,18 @@
 */
 package org.openhab.core.io.rest.core.link;

+import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.openhab.core.thing.link.ItemChannelLinkRegistry.ItemChannelLinkProblem;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * Transfer object for broken item channel links.
 *
 * @author Arne Seime - Initial contribution
 */
+@Schema(name = "BrokenItemChannelLink")
+@NonNullByDefault
 public class BrokenItemChannelLinkDTO {
    public EnrichedItemChannelLinkDTO itemChannelLink;

@@ -14,14 +14,19 @@ package org.openhab.core.io.rest.core.link;

 import java.util.Map;

+import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.openhab.core.thing.link.dto.ItemChannelLinkDTO;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is an enriched data transfer object that is used to serialize items channel links with dynamic data like the
 * editable flag.
 *
 * @author Christoph Weitkamp - Initial contribution
 */
+@Schema(name = "EnrichedItemChannelLink")
+@NonNullByDefault
 public class EnrichedItemChannelLinkDTO extends ItemChannelLinkDTO {

    public Boolean editable;
@@ -12,21 +12,32 @@
 */
 package org.openhab.core.io.rest.core.service;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * {@link ConfigurableServiceDTO} is a data transfer object for configurable services.
 *
 * @author Dennis Nobel - Initial contribution
 * @author Stefan Triller - added multiple field
 */
+@Schema(name = "ConfigurableService")
+@NonNullByDefault
 public class ConfigurableServiceDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String id;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String label;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String category;
-    public String configDescriptionURI;
+    public @Nullable String configDescriptionURI;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public boolean multiple;

-    public ConfigurableServiceDTO(String id, String label, String category, String configDescriptionURI,
+    public ConfigurableServiceDTO(String id, String label, String category, @Nullable String configDescriptionURI,
            boolean multiple) {
        this.id = id;
        this.label = label;
@@ -17,13 +17,17 @@ import java.util.Set;

 import org.openhab.core.thing.dto.ChannelDTO;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize channels with dynamic data like linked items.
 *
 * @author Kai Kreuzer - Initial contribution
 */
+@Schema(name = "EnrichedChannel")
 public class EnrichedChannelDTO extends ChannelDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public final Set<String> linkedItems;

    public EnrichedChannelDTO(ChannelDTO channelDTO, Set<String> linkedItems) {
@@ -14,11 +14,15 @@ package org.openhab.core.io.rest.core.thing;

 import java.util.List;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.core.thing.ThingStatusInfo;
 import org.openhab.core.thing.dto.AbstractThingDTO;
 import org.openhab.core.thing.dto.ThingDTO;
 import org.openhab.core.thing.firmware.dto.FirmwareStatusDTO;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize things with dynamic data like the status.
 *
@@ -28,11 +32,16 @@ import org.openhab.core.thing.firmware.dto.FirmwareStatusDTO;
 * @author Wouter Born - Let (Enriched)ThingDTO extend AbstractThingDTO so both can define their own "channels" type
 * @author Andrew Fiddian-Green - Added semanticEquipmentTag
 */
+@Schema(name = "EnrichedThing")
+@NonNullByDefault
 public class EnrichedThingDTO extends AbstractThingDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<EnrichedChannelDTO> channels;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public ThingStatusInfo statusInfo;
-    public FirmwareStatusDTO firmwareStatus;
+    public @Nullable FirmwareStatusDTO firmwareStatus;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public boolean editable;

    /**
@@ -45,7 +54,7 @@ public class EnrichedThingDTO extends AbstractThingDTO {
     * @param editable true if this thing can be edited
     */
    EnrichedThingDTO(ThingDTO thingDTO, List<EnrichedChannelDTO> channels, ThingStatusInfo statusInfo,
-            FirmwareStatusDTO firmwareStatus, boolean editable) {
+            @Nullable FirmwareStatusDTO firmwareStatus, boolean editable) {
        super(thingDTO.thingTypeUID, thingDTO.UID, thingDTO.label, thingDTO.bridgeUID, thingDTO.configuration,
                thingDTO.properties, thingDTO.location, thingDTO.semanticEquipmentTag);
        this.channels = channels;
@@ -17,6 +17,8 @@ import java.util.List;
 import java.util.Map;
 import java.util.Set;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.core.thing.Thing;
 import org.openhab.core.thing.ThingStatusInfo;
 import org.openhab.core.thing.dto.ChannelDTO;
@@ -30,6 +32,7 @@ import org.openhab.core.thing.firmware.dto.FirmwareStatusDTO;
 *
 * @author Dennis Nobel - Initial contribution
 */
+@NonNullByDefault
 public class EnrichedThingDTOMapper extends ThingDTOMapper {

    /**
@@ -42,8 +45,9 @@ public class EnrichedThingDTOMapper extends ThingDTOMapper {
     * @param editable true if this thing can be edited
     * @return the enriched thing DTO object
     */
-    public static EnrichedThingDTO map(Thing thing, ThingStatusInfo thingStatusInfo, FirmwareStatusDTO firmwareStatus,
-            Map<String, Set<String>> linkedItemsMap, boolean editable) {
+    public static EnrichedThingDTO map(Thing thing, ThingStatusInfo thingStatusInfo,
+            @Nullable FirmwareStatusDTO firmwareStatus, @Nullable Map<String, Set<String>> linkedItemsMap,
+            boolean editable) {
        ThingDTO thingDTO = ThingDTOMapper.map(thing);

        List<EnrichedChannelDTO> channels = new ArrayList<>();
@@ -12,6 +12,8 @@
 */
 package org.openhab.core.io.rest.sitemap.internal;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize command mappings.
 *
@@ -20,6 +22,7 @@ package org.openhab.core.io.rest.sitemap.internal;
 * @author Laurent Garnier - Replace field position by fields row and column
 * @author Laurent Garnier - New field releaseCommand
 */
+@Schema(name = "Mapping")
 public class MappingDTO {

    public Integer row;
@@ -15,11 +15,14 @@ package org.openhab.core.io.rest.sitemap.internal;
 import java.util.ArrayList;
 import java.util.List;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize page content.
 *
 * @author Kai Kreuzer - Initial contribution
 */
+@Schema(name = "Page")
 public class PageDTO {

    public String id;
@@ -12,12 +12,15 @@
 */
 package org.openhab.core.io.rest.sitemap.internal;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize sitemaps.
 * 
 * @author Kai Kreuzer - Initial contribution
 * @author Chris Jackson - Initial contribution
 */
+@Schema(name = "Sitemap")
 public class SitemapDTO {

    public String name;
@@ -18,6 +18,8 @@ import java.util.List;

 import org.openhab.core.io.rest.core.item.EnrichedItemDTO;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize widgets.
 *
@@ -30,6 +32,7 @@ import org.openhab.core.io.rest.core.item.EnrichedItemDTO;
 * @author Laurent Garnier - Remove field columns
 * @author Laurent Garnier - New fields row, column, command, releaseCommand and stateless for Button element
 */
+@Schema(name = "Widget")
 public class WidgetDTO {

    public String widgetId;
@@ -17,11 +17,14 @@ import java.util.Map;
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.openhab.core.transform.Transformation;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * The {@link TransformationDTO} wraps a {@link Transformation}
 *
 * @author Jan N. Klug - Initial contribution
 */
+@Schema(name = "Transformation")
@NonNullByDefault
 public class TransformationDTO {
    public String uid;
@@ -15,17 +15,23 @@ package org.openhab.core.io.rest.ui;
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object for a UI tile.
 *
 * @author Yannick Schaus - Initial contribution
 */
+@Schema(name = "Tile")
@NonNullByDefault
 public class TileDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String name;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String url;
    public @Nullable String overlay;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String imageUrl;

    public TileDTO(String name, String url, @Nullable String overlay, String imageUrl) {
@@ -16,13 +16,18 @@ import java.util.Set;

 import org.openhab.core.voice.text.HumanLanguageInterpreter;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * A DTO that is used on the REST API to provide infos about {@link HumanLanguageInterpreter} to UIs.
 *
 * @author Kai Kreuzer - Initial contribution
 */
+@Schema(name = "HumanLanguageInterpreter")
 public class HumanLanguageInterpreterDTO {
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String id;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String label;
    public Set<String> locales;
 }
@@ -14,11 +14,14 @@ package org.openhab.core.io.rest.voice.internal;

 import org.openhab.core.voice.Voice;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * A DTO that is used on the REST API to provide infos about {@link Voice} to UIs.
 *
 * @author Laurent Garnier - Initial contribution
 */
+@Schema(name = "Voice")
 public class VoiceDTO {
    public String id;
    public String label;
@@ -22,6 +22,8 @@ import org.openhab.core.i18n.TimeZoneProvider;
 import org.openhab.core.i18n.UnitProvider;
 import org.openhab.core.io.rest.RESTConstants;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a java bean that is used to define the root entry
 * page of the REST interface.
@@ -36,6 +38,7 @@ public class RootBean {

    public final String locale;

+    @Schema(allowableValues = { "SI", "US" })
    public final String measurementSystem;

    public final String timezone;
@@ -20,15 +20,17 @@ import org.openhab.core.library.types.DecimalType;
 import org.openhab.core.library.types.QuantityType;
 import org.openhab.core.types.State;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a java bean that is used to serialize items to JSON.
 *
 * @author Chris Jackson - Initial contribution
 */
+@Schema(name = "ItemHistory")
 public class ItemHistoryDTO {

    public String name;
-    public String totalrecords;
    public String datapoints;

    public List<HistoryDataBean> data = new ArrayList<>();
@@ -14,12 +14,15 @@ package org.openhab.core.persistence.dto;

 import org.eclipse.jdt.annotation.NonNullByDefault;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * The {@link PersistenceCronStrategyDTO} is used for transferring persistence cron
 * strategies
 *
 * @author Jan N. Klug - Initial contribution
 */
+@Schema(name = "PersistenceCronStrategy")
@NonNullByDefault
 public class PersistenceCronStrategyDTO {
    public String name = "";
@@ -15,13 +15,17 @@ package org.openhab.core.persistence.dto;
 import java.math.BigDecimal;
 import java.util.List;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * The {@link org.openhab.core.persistence.dto.PersistenceFilterDTO} is used for transferring persistence filter
 * configurations
 *
 * @author Jan N. Klug - Initial contribution
 */
+@Schema(name = "PersistenceFilter")
 public class PersistenceFilterDTO {
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String name;

    // threshold and time
@@ -17,12 +17,15 @@ import java.util.List;

 import org.eclipse.jdt.annotation.NonNullByDefault;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * The {@link org.openhab.core.persistence.dto.PersistenceItemConfigurationDTO} is used for transferring persistence
 * item configurations
 *
 * @author Jan N. Klug - Initial contribution
 */
+@Schema(name = "PersistenceItemConfiguration")
@NonNullByDefault
 public class PersistenceItemConfigurationDTO {
    public Collection<String> items = List.of();
@@ -19,12 +19,15 @@ import java.util.Map;
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * The {@link PersistenceServiceConfigurationDTO} is used for transferring persistence service configurations
 *
 * @author Jan N. Klug - Initial contribution
 * @author Mark Herwege - Make default strategy to be only a configuration suggestion
 */
+@Schema(name = "PersistenceServiceConfiguration")
@NonNullByDefault
 public class PersistenceServiceConfigurationDTO {
    public String serviceId = "";
@@ -12,11 +12,14 @@
 */
 package org.openhab.core.persistence.dto;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a java bean that is used to serialize services to JSON.
 *
 * @author Chris Jackson - Initial contribution
 */
+@Schema(name = "PersistenceService")
 public class PersistenceServiceDTO {
    public PersistenceServiceDTO() {
    }
@@ -14,11 +14,14 @@ package org.openhab.core.persistence.dto;

 import org.eclipse.jdt.annotation.NonNullByDefault;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * The {@link PersistenceStrategyDTO} is used for transferring persistence strategies.
 *
 * @author Jan N. Klug - Initial contribution
 */
+@Schema(name = "PersistenceStrategy")
@NonNullByDefault
 public class PersistenceStrategyDTO {
    public String type;
@@ -17,6 +17,8 @@ import java.util.Objects;
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * A {@link ThingStatusInfo} represents status information of a thing which consists of
 * <ul>
@@ -31,8 +33,10 @@ import org.eclipse.jdt.annotation.Nullable;
@NonNullByDefault
 public class ThingStatusInfo {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    private final ThingStatus status;

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    private final ThingStatusDetail statusDetail;

    private @Nullable String description;
@@ -14,6 +14,8 @@ package org.openhab.core.thing.dto;

 import java.util.Map;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize things.
 *
@@ -28,9 +30,13 @@ public abstract class AbstractThingDTO {

    public String label;
    public String bridgeUID;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Map<String, Object> configuration;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Map<String, String> properties;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String UID;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String thingTypeUID;
    public String location;
    public String semanticEquipmentTag;
@@ -22,6 +22,8 @@ import org.openhab.core.thing.ChannelUID;
 import org.openhab.core.thing.type.AutoUpdatePolicy;
 import org.openhab.core.thing.type.ChannelKind;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize channels.
 *
@@ -29,17 +31,24 @@ import org.openhab.core.thing.type.ChannelKind;
 * @author Chris Jackson - Added properties and configuration
 * @author Kai Kreuzer - Added default tags
 */
+@Schema(name = "Channel")
 public class ChannelDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String uid;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String id;
    public String channelTypeUID;
    public String itemType;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String kind;
    public String label;
    public String description;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Set<String> defaultTags;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Map<String, String> properties;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Map<String, Object> configuration;
    public String autoUpdatePolicy;

@@ -15,31 +15,46 @@ package org.openhab.core.thing.dto;
 import java.util.Map;
 import java.util.Set;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.core.types.StateDescription;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize channel definitions.
 *
 * @author Dennis Nobel - Initial contribution
 * @author Chris Jackson - Added properties
 */
+@Schema(name = "ChannelDefinition")
+@NonNullByDefault
 public class ChannelDefinitionDTO {

-    public String description;
+    public @Nullable String description;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String id;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String label;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Set<String> tags;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Map<String, String> properties;
-    public String category;
-    public StateDescription stateDescription;
+    public @Nullable String category;
+    public @Nullable StateDescription stateDescription;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public boolean advanced;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String typeUID;

+    // do not remove - needed by GSON
    public ChannelDefinitionDTO() {
+        this("", "", "", null, Set.of(), null, null, false, Map.of());
    }

-    public ChannelDefinitionDTO(String id, String typeUID, String label, String description, Set<String> tags,
-            String category, StateDescription stateDescription, boolean advanced, Map<String, String> properties) {
+    public ChannelDefinitionDTO(String id, String typeUID, String label, @Nullable String description, Set<String> tags,
+            @Nullable String category, @Nullable StateDescription stateDescription, boolean advanced,
+            Map<String, String> properties) {
        this.description = description;
        this.label = label;
        this.id = id;
@@ -14,22 +14,34 @@ package org.openhab.core.thing.dto;

 import java.util.List;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize channel group definitions.
 *
 * @author Dennis Nobel - Initial contribution
 */
+@Schema(name = "ChannelGroupDefinition")
+@NonNullByDefault
 public class ChannelGroupDefinitionDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String id;
-    public String description;
-    public String label;
+    public @Nullable String description;
+    public @Nullable String label;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<ChannelDefinitionDTO> channels;

+    // do not remove - needed by GSON
    public ChannelGroupDefinitionDTO() {
+        this("", null, null, List.of());
    }

-    public ChannelGroupDefinitionDTO(String id, String label, String description, List<ChannelDefinitionDTO> channels) {
+    public ChannelGroupDefinitionDTO(String id, @Nullable String label, @Nullable String description,
+            List<ChannelDefinitionDTO> channels) {
        this.id = id;
        this.label = label;
        this.description = description;
@@ -15,41 +15,57 @@ package org.openhab.core.thing.dto;
 import java.util.List;
 import java.util.Set;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.core.config.core.dto.ConfigDescriptionParameterDTO;
 import org.openhab.core.config.core.dto.ConfigDescriptionParameterGroupDTO;
 import org.openhab.core.thing.type.ChannelKind;
 import org.openhab.core.types.CommandDescription;
 import org.openhab.core.types.StateDescription;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used with to serialize channel types.
 *
 * @author Chris Jackson - Initial contribution
 * @author Mark Herwege - added unit hint
 */
+@Schema(name = "ChannelType")
+@NonNullByDefault
 public class ChannelTypeDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<ConfigDescriptionParameterDTO> parameters;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<ConfigDescriptionParameterGroupDTO> parameterGroups;
-    public String description;
+    public @Nullable String description;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String label;
-    public String category;
-    public String itemType;
-    public String unitHint;
+    public @Nullable String category;
+    public @Nullable String itemType;
+    public @Nullable String unitHint;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED, allowableValues = { "STATE", "TRIGGER" })
    public String kind;
-    public StateDescription stateDescription;
+    public @Nullable StateDescription stateDescription;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public Set<String> tags;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String UID;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public boolean advanced;
-    public CommandDescription commandDescription;
+    public @Nullable CommandDescription commandDescription;

+    // do not remove - needed by GSON
    public ChannelTypeDTO() {
+        this("", "", null, null, null, null, ChannelKind.STATE, List.of(), List.of(), null, Set.of(), false, null);
    }

-    public ChannelTypeDTO(String uid, String label, String description, String category, String itemType,
-            String unitHint, ChannelKind kind, List<ConfigDescriptionParameterDTO> parameters,
-            List<ConfigDescriptionParameterGroupDTO> parameterGroups, StateDescription stateDescription,
-            Set<String> tags, boolean advanced, CommandDescription commandDescription) {
+    public ChannelTypeDTO(String uid, String label, @Nullable String description, @Nullable String category,
+            @Nullable String itemType, @Nullable String unitHint, ChannelKind kind,
+            List<ConfigDescriptionParameterDTO> parameters, List<ConfigDescriptionParameterGroupDTO> parameterGroups,
+            @Nullable StateDescription stateDescription, Set<String> tags, boolean advanced,
+            @Nullable CommandDescription commandDescription) {
        this.UID = uid;
        this.label = label;
        this.description = description;
@@ -14,6 +14,11 @@ package org.openhab.core.thing.dto;

 import java.util.List;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize stripped thing types.
 * Stripped thing types exclude the parameters, configDescription and channels
@@ -21,22 +26,32 @@ import java.util.List;
 * @author Miki Jankov - Initial contribution
 * @author Andrew Fiddian-Green - Added semanticEquipmentTag
 */
+@Schema(name = "StrippedThingType")
+@NonNullByDefault
 public class StrippedThingTypeDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String UID;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String label;
-    public String description;
-    public String category;
+    public @Nullable String description;
+    public @Nullable String category;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public boolean listed;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<String> supportedBridgeTypeUIDs;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public boolean bridge;
-    public String semanticEquipmentTag;
+    public @Nullable String semanticEquipmentTag;

+    // do not remove - needed by GSON
    public StrippedThingTypeDTO() {
+        this("", "", null, null, true, List.of(), false, null);
    }

-    public StrippedThingTypeDTO(String uid, String label, String description, String category, boolean listed,
-            List<String> supportedBridgeTypeUIDs, boolean bridge, String semanticEquipmentTag) {
+    public StrippedThingTypeDTO(String uid, String label, @Nullable String description, @Nullable String category,
+            boolean listed, List<String> supportedBridgeTypeUIDs, boolean bridge,
+            @Nullable String semanticEquipmentTag) {
        this.UID = uid;
        this.label = label;
        this.description = description;
@@ -15,6 +15,8 @@ package org.openhab.core.thing.dto;
 import java.util.List;
 import java.util.Map;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize things.
 *
@@ -25,8 +27,10 @@ import java.util.Map;
 * @author Wouter Born - Let (Enriched)ThingDTO extend AbstractThingDTO so both can define their own "channels" type
 * @author Andrew Fiddian-Green - Added semanticEquipmentTag
 */
+@Schema(name = "Thing")
 public class ThingDTO extends AbstractThingDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public List<ChannelDTO> channels;

    public ThingDTO() {
@@ -15,9 +15,13 @@ package org.openhab.core.thing.dto;
 import java.util.List;
 import java.util.Map;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
 import org.openhab.core.config.core.dto.ConfigDescriptionParameterDTO;
 import org.openhab.core.config.core.dto.ConfigDescriptionParameterGroupDTO;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used with to serialize thing types.
 *
@@ -27,6 +31,8 @@ import org.openhab.core.config.core.dto.ConfigDescriptionParameterGroupDTO;
 * @author Miki Jankov - Introducing StrippedThingTypeDTO
 * @author Andrew Fiddian-Green - Added semanticEquipmentTag
 */
+@Schema(name = "ThingType")
+@NonNullByDefault
 public class ThingTypeDTO extends StrippedThingTypeDTO {

    public List<ChannelDefinitionDTO> channels;
@@ -36,14 +42,17 @@ public class ThingTypeDTO extends StrippedThingTypeDTO {
    public Map<String, String> properties;
    public List<String> extensibleChannelTypeIds;

+    // do not remove - needed by GSON
    public ThingTypeDTO() {
+        this("", "", null, null, true, List.of(), List.of(), List.of(), List.of(), Map.of(), false, List.of(),
+                List.of(), null);
    }

-    public ThingTypeDTO(String uid, String label, String description, String category, boolean listed,
-            List<ConfigDescriptionParameterDTO> configParameters, List<ChannelDefinitionDTO> channels,
+    public ThingTypeDTO(String uid, String label, @Nullable String description, @Nullable String category,
+            boolean listed, List<ConfigDescriptionParameterDTO> configParameters, List<ChannelDefinitionDTO> channels,
            List<ChannelGroupDefinitionDTO> channelGroups, List<String> supportedBridgeTypeUIDs,
            Map<String, String> properties, boolean bridge, List<ConfigDescriptionParameterGroupDTO> parameterGroups,
-            List<String> extensibleChannelTypeIds, String semanticEquipmentTag) {
+            List<String> extensibleChannelTypeIds, @Nullable String semanticEquipmentTag) {
        this.UID = uid;
        this.label = label;
        this.description = description;
@@ -15,19 +15,25 @@ package org.openhab.core.thing.firmware.dto;
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize firmware information.
 *
 * @author Aoun Bukhari - Initial contribution
 * @author Dimitar Ivanov - enriched with thing type UID
 */
+@Schema(name = "Firmware")
@NonNullByDefault
 public class FirmwareDTO {
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public final String thingTypeUID;
    public final @Nullable String vendor;
    public final @Nullable String model;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public final boolean modelRestricted;
    public final @Nullable String description;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public final String version;
    public final @Nullable String changelog;
    public final @Nullable String prerequisiteVersion;
@@ -15,14 +15,18 @@ package org.openhab.core.thing.firmware.dto;
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize firmware status information.
 *
 * @author Aoun Bukhari - Initial contribution
 */
+@Schema(name = "FirmwareStatus")
@NonNullByDefault
 public class FirmwareStatusDTO {
    public final String status;
+    @Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED)
    public final @Nullable String updatableVersion;

    public FirmwareStatusDTO(String status, @Nullable String updatableVersion) {
@@ -12,11 +12,14 @@
 */
 package org.openhab.core.thing.link.dto;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+
 /**
 * This is an abstract class for link data transfer object that is used to serialize links.
 *
 * @author Dennis Nobel - Initial contribution
 */
+@NonNullByDefault
 public abstract class AbstractLinkDTO {

    public String itemName;
@@ -25,6 +28,7 @@ public abstract class AbstractLinkDTO {
     * Default constructor for deserialization e.g. by Gson.
     */
    protected AbstractLinkDTO() {
+        this("");
    }

    protected AbstractLinkDTO(String itemName) {
@@ -14,11 +14,17 @@ package org.openhab.core.thing.link.dto;

 import java.util.Map;

+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize links.
 *
 * @author Dennis Nobel - Initial contribution
 */
+@Schema(name = "ItemChannelLink")
+@NonNullByDefault
 public class ItemChannelLinkDTO extends AbstractLinkDTO {

    public String channelUID;
@@ -28,6 +34,7 @@ public class ItemChannelLinkDTO extends AbstractLinkDTO {
     * Default constructor for deserialization e.g. by Gson.
     */
    protected ItemChannelLinkDTO() {
+        this("", "", Map.of());
    }

    public ItemChannelLinkDTO(String itemName, String channelUID, Map<String, Object> configuration) {
@@ -13,12 +13,19 @@
 package org.openhab.core.thing.profiles.dto;

 import java.util.Collection;
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+import io.swagger.v3.oas.annotations.media.Schema;

 /**
 * DTO for profile types
 *
 * @author Stefan Triller - Initial contribution
 */
+@Schema(name = "ProfileType")
+@NonNullByDefault
 public class ProfileTypeDTO {

    public String uid;
@@ -26,7 +33,9 @@ public class ProfileTypeDTO {
    public String kind;
    public Collection<String> supportedItemTypes;

+    // do not remove - needed by GSON
    public ProfileTypeDTO() {
+        this("", "", "", Set.of());
    }

    public ProfileTypeDTO(String uid, String label, String kind, Collection<String> supportedItemTypes) {
@@ -3,8 +3,9 @@ Bundle-Activator: org.openhab.core.ui.internal.UIActivator
 Private-Package: \
  org.knowm.xchart.*
 Import-Package: \
+  io.swagger.v3.oas.annotations.*;resolution:=optional,\
  de.erichseifert.vectorgraphics2d.*;resolution:=optional,\
  de.rototor.pdfbox.*;resolution:=optional,\
  com.madgag.*;resolution:=optional,\
  org.apache.pdfbox.*;resolution:=optional,\
-  *
+  *
@@ -17,6 +17,9 @@ import java.util.HashMap;
 import java.util.List;
 import java.util.Map;

+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.media.Schema.AdditionalPropertiesValue;
+
 /**
 * A UIComponent represents a piece of UI element for a client frontend to render; it is kept very simple and delegates
 * the actual rendering and behavior to the frontend.
@@ -33,6 +36,7 @@ import java.util.Map;
 public class UIComponent {
    String component;

+    @Schema(additionalProperties = AdditionalPropertiesValue.TRUE)
    Map<String, Object> config;

    Map<String, List<UIComponent>> slots = null;
@@ -59,6 +63,7 @@ public class UIComponent {
     *
     * @return the component type
     */
+    @Schema(hidden = true)
    public String getType() {
        return component;
    }
@@ -12,13 +12,17 @@
 */
 package org.openhab.core.items.dto;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize group functions.
 *
 * @author Kai Kreuzer - Initial contribution
 */
+@Schema(name = "GroupFunction")
 public class GroupFunctionDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String name;
    public String[] params;
 }
@@ -12,11 +12,14 @@
 */
 package org.openhab.core.items.dto;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize group items.
 *
 * @author Kai Kreuzer - Initial contribution
 */
+@Schema(name = "GroupItem")
 public class GroupItemDTO extends ItemDTO {

    public String groupType;
@@ -15,15 +15,19 @@ package org.openhab.core.items.dto;
 import java.util.List;
 import java.util.Set;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize items.
 *
 * @author Kai Kreuzer - Initial contribution
 * @author Andre Fuechsel - added tag support
 */
+@Schema(name = "Item")
 public class ItemDTO {
-
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String type;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public String name;
    public String label;
    public String category;
@@ -17,15 +17,20 @@ import java.util.Map;
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;

+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
 * This is a data transfer object that is used to serialize metadata for a certain namespace and item.
 *
 * @author Kai Kreuzer - Initial contribution
 */
+@Schema(name = "Metadata")
@NonNullByDefault
 public class MetadataDTO {

+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public @Nullable String value;
    public @Nullable Map<String, Object> config;
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
    public @Nullable Boolean editable;
 }
@@ -80,6 +80,7 @@
    <!-- Eclipse Java formatter version 4.26+ does not check test files -->
    <spotless.eclipse.version>4.25</spotless.eclipse.version>
    <spotless.eclipse.wtp.version>4.21.0</spotless.eclipse.wtp.version>
+    <swagger.version>2.2.35</swagger.version>

    <!-- TEST -->
    <!-- cxf can be updated independently, karaf only uses it in tests -->
@@ -367,6 +368,14 @@ Import-Package: \\
                <head>Implementation note:</head>
              </tag>
            </tags>
+            <additionalDependencies>
+              <dependency>
+                <groupId>io.swagger.core.v3</groupId>
+                <artifactId>swagger-annotations</artifactId>
+                <version>${swagger.version}</version>
+                <scope>compile</scope>
+              </dependency>
+            </additionalDependencies>
          </configuration>
        </plugin>