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
Generate and publish OpenAPI specification (#3116)
Wouter Borndcb45ee4b528
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.tomlindex 6577ec959..7c4169b2b 100644--- a/gradle/libs.versions.toml+++ b/gradle/libs.versions.toml@@ -199,4 +199,5 @@ axionRelease = { id = "pl.allegro.tech.build.axion-release", version.ref = "axiofileEncrypt = { id = "io.openremote.com.cherryperry.gradle-file-encrypt", version.ref = "fileEncrypt" }nexusPublish = { id = "io.github.gradle-nexus.publish-plugin", version.ref = "nexusPublish" }protobuf = { id = "com.google.protobuf", version.ref = "protobufPlugin" }+swagger = { id = "io.swagger.core.v3.swagger-gradle-plugin", version.ref = "swagger" }testLogger = { id = "com.adarshr.test-logger", version.ref = "testLogger" }diff --git a/manager/build.gradle b/manager/build.gradleindex 13b82fe0b..d45d3529c 100644--- a/manager/build.gradle+++ b/manager/build.gradle@@ -7,6 +7,7 @@ plugins {id 'distribution'id 'maven-publish'id 'signing'+ alias libs.plugins.swagger}application {@@ -103,6 +104,26 @@ afterEvaluate {tasks.run.workingDir = rootProject.projectDir}+resolve {+ outputFileName = 'openapi'+ outputFormat = 'JSON'+ outputDir = layout.buildDirectory.dir("openapi")++ prettyPrint = true+ sortOutput = true+ defaultResponseCode = '200'++ classpath = sourceSets.main.runtimeClasspath++ // Required so that the plugin itself uses the Jakarta Swagger/JAX-RS+ // dependencies from the OpenRemote runtime classpath.+ buildClasspath = sourceSets.main.runtimeClasspath++ resourcePackages = ['org.openremote.model']+ openApiFile = layout.projectDirectory.file('src/main/resources/openapi-base.yaml')+ objectMapperProcessorClass = 'org.openremote.manager.web.ManagerObjectMapperProcessor'+}+tasks.withType(Sync).configureEach {duplicatesStrategy = DuplicatesStrategy.EXCLUDE}@@ -140,12 +161,21 @@ java {withSourcesJar()}+def openApiFile = layout.buildDirectory.file('openapi/openapi.json')+publishing {publications {maven(MavenPublication) {group = "io.openremote"artifactId = "openremote-${project.name}"from components.java++ artifact(openApiFile) {+ classifier = 'openapi'+ extension = 'json'+ builtBy tasks.named('resolve')+ }+pom {name = 'OpenRemote Manager'description = 'Provides core container services and is the main component of the OpenRemote backend; add maven {url "https://repo.osgeo.org/repository/release/"} and maven {url "https://pkgs.dev.azure.com/OpenRemote/OpenRemote/_packaging/OpenRemote/maven/v1"} to resolve all dependencies'@@ -196,6 +226,16 @@ signing {}}+tasks.named('resolve') {+ dependsOn tasks.named('classes')+}++tasks.register('generateOpenApi') {+ group = 'documentation'+ description = 'Generates the OpenRemote OpenAPI specification'+ dependsOn tasks.named('resolve')+}+// Output version.properties filetasks.register('setVersionProperties', WriteProperties) {destinationFile = Paths.get(projectDir.path, "src", "main", "resources", "version.properties").toFile()diff --git a/manager/src/main/java/org/openremote/manager/web/ManagerObjectMapperProcessor.java b/manager/src/main/java/org/openremote/manager/web/ManagerObjectMapperProcessor.javanew file mode 100644index 000000000..535c33240--- /dev/null+++ b/manager/src/main/java/org/openremote/manager/web/ManagerObjectMapperProcessor.java@@ -0,0 +1,71 @@+/*+ * 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.manager.web;++import com.fasterxml.jackson.annotation.JsonProperty;+import com.fasterxml.jackson.databind.ObjectMapper;+import io.swagger.v3.oas.integration.api.ObjectMapperProcessor;+import io.swagger.v3.oas.models.media.StringSchema;+import io.swagger.v3.oas.models.servers.ServerVariable;+import org.openremote.model.util.ValueUtil;++import java.util.List;++/**+ * Applies the manager's Jackson configuration when Swagger generates an OpenAPI document outside the running manager.+ */+public class ManagerObjectMapperProcessor implements ObjectMapperProcessor {++ private abstract static class ServerVariableMixin {+ @JsonProperty("default")+ List<String> _default;+ }++ private abstract static class StringSchemaMixin {+ @JsonProperty("enum")+ protected List<String> _enum;+ }++ public static void configure(ObjectMapper objectMapper) {+ ValueUtil.configureObjectMapper(objectMapper);+ objectMapper.addMixIn(StringSchema.class, StringSchemaMixin.class);+ objectMapper.addMixIn(ServerVariable.class, ServerVariableMixin.class);+ }++ @Override+ public void processJsonObjectMapper(ObjectMapper objectMapper) {+ configure(objectMapper);+ }++ @Override+ public void processYamlObjectMapper(ObjectMapper objectMapper) {+ configure(objectMapper);+ }++ @Override+ public void processOutputJsonObjectMapper(ObjectMapper objectMapper) {+ configure(objectMapper);+ }++ @Override+ public void processOutputYamlObjectMapper(ObjectMapper objectMapper) {+ configure(objectMapper);+ }+}diff --git a/manager/src/main/java/org/openremote/manager/web/ManagerWebService.java b/manager/src/main/java/org/openremote/manager/web/ManagerWebService.javaindex 511c3d627..5ae3144b1 100644--- a/manager/src/main/java/org/openremote/manager/web/ManagerWebService.java+++ b/manager/src/main/java/org/openremote/manager/web/ManagerWebService.java@@ -21,6 +21,7 @@ package org.openremote.manager.web;import com.fasterxml.jackson.annotation.JsonProperty;import io.swagger.v3.core.util.Json;+import io.swagger.v3.core.util.Yaml;import io.swagger.v3.jaxrs2.integration.resources.OpenApiResource;import io.swagger.v3.oas.integration.SwaggerConfiguration;import io.swagger.v3.oas.models.OpenAPI;@@ -39,6 +40,8 @@ import org.openremote.model.Container;import org.openremote.model.util.Config;import org.openremote.model.util.TextUtil;+import java.io.IOException;+import java.io.InputStream;import java.net.URL;import java.nio.file.Files;import java.nio.file.Path;@@ -143,49 +146,29 @@ public class ManagerWebService extends WebService {}protected Object getOpenApiResource() {- // Modify swagger object mapper to match ours- configureObjectMapper(Json.mapper());- Json.mapper().addMixIn(StringSchema.class, StringSchemaMixin.class);- Json.mapper().addMixIn(ServerVariable.class, ServerVariableMixin.class);-- // Add swagger resource- OpenAPI oas = new OpenAPI()- .servers(List.of(new Server().url("/api/{realm}/").variables(new ServerVariables().addServerVariable("realm", new ServerVariable()._default("master")))))- .schemaRequirement("openid", new SecurityScheme().type(SecurityScheme.Type.OAUTH2).flows(- new OAuthFlows() //- .authorizationCode(- new OAuthFlow()- .authorizationUrl("/auth/realms/master/protocol/openid-connect/auth")- .refreshUrl("/auth/realms/master/protocol/openid-connect/token")- .tokenUrl("/auth/realms/master/protocol/openid-connect/token")- .scopes(new Scopes().addString("profile", "profile"))- )- .clientCredentials(- // for service users- new OAuthFlow()- .tokenUrl("/auth/realms/master/protocol/openid-connect/token")- .refreshUrl("/auth/realms/master/protocol/openid-connect/token")- .scopes(new Scopes().addString("profile", "profile"))- )- )).security(List.of(new SecurityRequirement().addList("openid")));-- Info info = new Info()- .title("OpenRemote Manager HTTP API")- .version("3.0.0")- .description("This is the documentation for the OpenRemote Manager HTTP API. Please see the [documentation](https://docs.openremote.io) for more info.")- .contact(new Contact().email("[email protected]"))- .license(new License().name("AGPL 3.0").url("https://www.gnu.org/licenses/agpl-3.0.en.html"));-- oas.info(info);+ ManagerObjectMapperProcessor.configure(Json.mapper());+SwaggerConfiguration oasConfig = new SwaggerConfiguration().resourcePackages(Set.of("org.openremote.model.*"))- .openAPI(oas)+ .openAPI(loadOpenApiBase()).defaultResponseCode("200");+OpenApiResource openApiResource = new OpenApiResource();openApiResource.openApiConfiguration(oasConfig);return openApiResource;}+ private OpenAPI loadOpenApiBase() {+ try (InputStream input = ManagerWebService.class.getResourceAsStream("/openapi-base.yaml")) {+ if (input == null) {+ throw new IllegalStateException("Cannot find /openapi-base.yaml");+ }+ return Yaml.mapper().readValue(input, OpenAPI.class);+ } catch (IOException e) {+ throw new IllegalStateException("Failed to load /openapi-base.yaml", e);+ }+ }+/*** Add resource/provider/etc. classes to enable REST API*/diff --git a/manager/src/main/resources/openapi-base.yaml b/manager/src/main/resources/openapi-base.yamlnew file mode 100644index 000000000..1b7fbd2e9--- /dev/null+++ b/manager/src/main/resources/openapi-base.yaml@@ -0,0 +1,39 @@+openapi: 3.0.1++info:+ title: OpenRemote Manager HTTP API+ version: 3.0.0+ description: >-+ This is the documentation for the OpenRemote Manager HTTP API.+ Please see the [documentation](https://docs.openremote.io) for more info.+ contact:+ email: [email protected]+ license:+ name: AGPL 3.0+ url: https://www.gnu.org/licenses/agpl-3.0.en.html++servers:+ - url: /api/{realm}/+ variables:+ realm:+ default: master++security:+ - openid: []++components:+ securitySchemes:+ openid:+ type: oauth2+ flows:+ authorizationCode:+ authorizationUrl: /auth/realms/master/protocol/openid-connect/auth+ tokenUrl: /auth/realms/master/protocol/openid-connect/token+ refreshUrl: /auth/realms/master/protocol/openid-connect/token+ scopes:+ profile: profile+ clientCredentials:+ tokenUrl: /auth/realms/master/protocol/openid-connect/token+ refreshUrl: /auth/realms/master/protocol/openid-connect/token+ scopes:+ profile: profile