[FEATURE] Support `servers` annotation options

[zongqichen]

Description

Hi Colleagues,

we have an issue: cap-js/ord#338. At the moment, openapi supports two terms: externalDocs and Extensions, is possible to support servers officially from cds annotation as well?

Best,
Zongqi

Suggested Solution

Support servers annotation

Alternatives

No response

Additional Context

No response

[daogrady]

Hi @zongqichen ,

please attach a minimal sample, so we can understand the expected output, as well a minimal input of how the model would look like the expected output should be generated from.

Best,
Daniel

[github-actions]

This issue has not been updated in a while. If it is still relevant, please comment on it to keep it open. The issue will be closed soon if it remains inactive.

[zongqichen]

Hi Daniel,

Here's a minimal sample:

CDS model:

@OpenAPI.servers: [
  { url: 'https://prod.example.com/api/v1', description: 'Production' },
  { url: 'https://sandbox.example.com/api/v1', description: 'Sandbox' }
]
service CatalogService {
  entity Books { key ID: Integer; title: String; }
}

Expected OpenAPI output:

{
  "openapi": "3.0.2",
  "info": { "title": "CatalogService", "version": "" },
  "servers": [
    { "url": "https://prod.example.com/api/v1", "description": "Production" },
    { "url": "https://sandbox.example.com/api/v1", "description": "Sandbox" }
  ]
}

The use case (cap-js/ord#338) is publishing API docs with production URLs to api.sap.com so customers can use "Try Out". Right now servers can only be set via compile option or config file — an annotation would be much more convenient and consistent with how @OpenAPI.externalDocs already works. What's your idea?

[github-actions]

This issue has not been updated in a while. If it is still relevant, please comment on it to keep it open. The issue will be closed soon if it remains inactive.