feat: support @OpenAPI.servers annotation for service-level server URLs (#339)

Add support for configuring OpenAPI servers via CDS annotation to enable
SAP Business Accelerator Hub "Try Out" feature with production URLs.

Closes #338

Author: zongqichen

__tests__/integration/cds-build.test.js

@@ -107,6 +107,22 @@ describe("ORD Build Integration Tests", () => {
                 }
             }
         });
+
+        test("should include @OpenAPI.servers annotation in OpenAPI document", () => {
+            const testServiceApi = ordDocument.apiResources.find((api) => api.ordId.includes("TestService"));
+            expect(testServiceApi).toBeDefined();
+
+            const openApiDef = testServiceApi.resourceDefinitions.find((def) => def.url.endsWith(".oas3.json"));
+            expect(openApiDef).toBeDefined();
+
+            const openApiPath = path.join(ORD_GEN_DIR, openApiDef.url);
+            const openApiContent = JSON.parse(fs.readFileSync(openApiPath, "utf-8"));
+
+            expect(openApiContent.servers).toBeDefined();
+            expect(openApiContent.servers).toHaveLength(2);
+            expect(openApiContent.servers[0].url).toBe("https://test-service.api.example.com");
+            expect(openApiContent.servers[1].url).toBe("https://test-service-sandbox.api.example.com");
+        });
     });
 
     describe("Failed Build", () => {

__tests__/integration/integration-test-app/srv/test-service.cds

@@ -20,3 +20,8 @@ annotate TestService with @ORD.Extensions: {
     visibility      : 'public',
     version         : '1.0.0'
 };
+
+annotate TestService with @OpenAPI.servers: [
+    { url: 'https://test-service.api.example.com', description: 'Production' },
+    { url: 'https://test-service-sandbox.api.example.com', description: 'Sandbox' }
+];

__tests__/unit/metaData.test.js

@@ -242,4 +242,40 @@ describe("metaData", () => {
         expect(result.contentType).toBe("application/json");
         expect(result.response).toBe("Content with compile options");
     });
+
+    describe("@OpenAPI.servers annotation", () => {
+        const url = "/ord/v1/ns:apiResource:TestService:v1/TestService.oas3.json";
+        let capturedOptions;
+
+        beforeEach(() => {
+            capturedOptions = null;
+            openapi.mockImplementation((csn, options) => {
+                capturedOptions = options;
+                return "content";
+            });
+        });
+
+        test("should pass servers from annotation to openapi compiler", async () => {
+            const servers = [{ url: "https://api.example.com", description: "Production" }];
+            const mockCsn = {
+                definitions: { TestService: { "@OpenAPI.servers": servers } },
+            };
+
+            await getMetadata(url, mockCsn);
+
+            expect(capturedOptions["openapi:servers"]).toBe(JSON.stringify(servers));
+        });
+
+        test.each([
+            ["missing", {}],
+            ["empty array", { "@OpenAPI.servers": [] }],
+            ["not an array", { "@OpenAPI.servers": "invalid" }],
+        ])("should not set servers when annotation is %s", async (_, serviceDef) => {
+            const mockCsn = { definitions: { TestService: serviceDef } };
+
+            await getMetadata(url, mockCsn);
+
+            expect(capturedOptions["openapi:servers"]).toBeUndefined();
+        });
+    });
 });

docs/ord.md

@@ -6,6 +6,7 @@
 2. [Configuration](#configuration)
     - [Global Application Settings](#1-overriding-global-application-information)
     - [Service-Level Customization](#2-overriding-service-level-information)
+    - [OpenAPI Servers](#3-openapi-servers-configuration)
 3. [Custom ORD Content](#adding-custom-ord-content)
 4. [Products](#adding-products)
     - [Using Existing SAP Products](#1-using-an-existing-sap-product)
@@ -66,6 +67,18 @@ annotate ProcessorService with @ORD.Extensions: {
 
 ---
 
+### 3. OpenAPI Servers Configuration
+
+Use `@OpenAPI.servers` to add production URLs to generated OpenAPI documents (for SAP Business Accelerator Hub "Try Out" feature):
+
+```js
+annotate MyService with @OpenAPI.servers: [
+    { url: 'https://my-service.api.sap.com', description: 'Production' }
+];
+```
+
+---
+
 ## Adding Custom ORD Content
 
 The ORD plugin allows adding **custom ORD content** via the `customOrdContentFile` setting in `.cdsrc.json`.
@@ -369,6 +382,7 @@ More information, see [ORD Document specification](https://pages.github.tools.sa
 | -------------------------------- | ----------------------------------------------------------------------- |
 | Global Metadata                  | Define in `.cdsrc.json` under `ord`                                     |
 | Service Metadata                 | Use `@ORD.Extensions` annotations in `.cds` files                       |
+| OpenAPI Servers                  | Use `@OpenAPI.servers` annotation                                       |
 | Custom ORD Content               | Use `customOrdContentFile`                                              |
 | Linking to Existing SAP Products | Use `existingProductORDId`                                              |
 | Defining Custom Products         | Add `products` section manually                                         |

lib/constants.js

@@ -77,6 +77,8 @@ const LEVEL = Object.freeze({
 
 const OPEN_RESOURCE_DISCOVERY_VERSION = "1.12";
 
+const OPENAPI_SERVERS_ANNOTATION = "@OpenAPI.servers";
+
 const ORD_EXTENSIONS_PREFIX = "@ORD.Extensions.";
 
 const ORD_ODM_ENTITY_NAME_ANNOTATION = "@ODM.entityName";
@@ -156,6 +158,7 @@ module.exports = {
     LEVEL,
     MCP_CUSTOM_TYPE,
     OPEN_RESOURCE_DISCOVERY_VERSION,
+    OPENAPI_SERVERS_ANNOTATION,
     ORD_ACCESS_STRATEGY,
     ORD_DOCUMENT_FILE_NAME,
     ORD_EXTENSIONS_PREFIX,

lib/metaData.js

@@ -1,12 +1,24 @@
 const cds = require("@sap/cds/lib");
 const { compile: openapi } = require("@cap-js/openapi");
 const { compile: asyncapi } = require("@cap-js/asyncapi");
-const { COMPILER_TYPES } = require("./constants");
+const { COMPILER_TYPES, OPENAPI_SERVERS_ANNOTATION } = require("./constants");
 const Logger = require("./logger");
 const { interopCSN } = require("./interopCsn.js");
 const cdsc = require("@sap/cds-compiler/lib/main");
 const { isMCPPluginReady, buildMcpServerDefinition } = require("./mcpAdapter");
 
+/**
+ * Read @OpenAPI.servers annotation from service definition
+ * @param {object} csn - The CSN model
+ * @param {string} serviceName - The service name
+ * @returns {string|undefined} - JSON string of servers array or undefined
+ */
+const _getServersFromAnnotation = (csn, serviceName) => {
+    const servers = csn?.definitions?.[serviceName]?.[OPENAPI_SERVERS_ANNOTATION];
+    const isValidServers = Array.isArray(servers) && servers.length > 0;
+    return isValidServers ? JSON.stringify(servers) : undefined;
+};
+
 const getMetadata = async (url, model = null) => {
     const parts = url
         ?.split("/")
@@ -23,7 +35,16 @@ const getMetadata = async (url, model = null) => {
     switch (compilerType) {
         case COMPILER_TYPES.oas3:
             try {
-                responseFile = openapi(csn, { ...options, ...(compileOptions?.openapi || {}) });
+                // Check for service-level @OpenAPI.servers annotation
+                const serversFromAnnotation = _getServersFromAnnotation(csn, serviceName);
+                const openapiOptions = { ...options, ...(compileOptions?.openapi || {}) };
+
+                // Service-level annotation takes precedence over global config
+                if (serversFromAnnotation) {
+                    openapiOptions["openapi:servers"] = serversFromAnnotation;
+                }
+
+                responseFile = openapi(csn, openapiOptions);
             } catch (error) {
                 Logger.error("OpenApi error:", error.message);
                 throw error;

xmpl/srv/services.cds

@@ -36,6 +36,18 @@ service LocalService {
 
 annotate LocalService with @ORD.Extensions: {title: 'This is Local Service title'};
 
+// Service-level OpenAPI servers configuration
+annotate LocalService with @OpenAPI.servers: [
+    {
+        url        : 'https://local-service.api.sap.com',
+        description: 'LocalService Production'
+    },
+    {
+        url        : 'https://local-service-sandbox.api.sap.com',
+        description: 'LocalService Sandbox'
+    }
+];
+
 annotate AdminService with @ORD.Extensions: {
     title         : 'This is Admin Service title',
     industry      : [