Skip to content

armgit / core

Public Imported from GitHub
0

100% open-source IoT Platform - Integrate your devices, add intelligence, build custom apps

Generate and publish OpenAPI specification (#3116)

Wouter Borndcb45ee4b528
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 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 = "axio
fileEncrypt = { 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.gradle
index 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 file
tasks.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.java
new file mode 100644
index 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.java
index 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.yaml
new file mode 100644
index 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:
+ 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