Azure / Azure/azure-functions-openapi-extension

Server listings per path not showing up in openapi 3.* spec

Open
#691 0 comments 0 reactions 0 assignees View on GitHub
feature: api-description Needs: Triage (Functions) potential-bug
Dominant language
C#
Stars
388
Forks
202
PR merge metrics
No merged PRs in 30d

Description

### Description

**Describe the bug**
As per OpenApi V3 it should be possible to override the server attribute for specific paths. See [here](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#overriding-servers). However when I try to append a Servers list to my OpenApiPathItem object. It does not get rendered in the final document. The fact that the OpenApiPathItem has a servers property strongly suggests that it is supported, but as far as I could see in the code base there is no implementation (I did have AI search the codebase so not 100% sure)? This is misleading at least. It is a bit of an edge case, but sometimes a necessary evil.
To be clear, it does generate a valid openapi spec, it's just missing the server attribute on the path.

### Steps to reproduce

**OpenApi File To Reproduce**
Example:
OpenApi File:
```
"/runtime/webhooks/durabletask/instances/{instanceId}": {
"get": {
"tags": [
"orchestration"
],
"summary": "Get orchestration instance status. Auto generated endpoint by Durable Function.",
"description": "Retrieves the status of a specific orchestration instance by ID.",
"operationId": "getOrchestrationInstanceStatus",
"produces": [
"application/json"
],
"parameters": [
... // shortened due to irrelevance
],
"responses": {
... // shortened due to irrelevance
}
}
}
```
**Expected behavior**
When listing a server for a path, it should be generated in the final openApiSpec as described in the openapi v3 specification.

**Screenshots/Code Snippets**
If applicable, add screenshots of the stack trace or a code snippet to help explain your problem.
If applicable, add a link to your project

Code
```
public class CustomDocumentFilters : DefaultOpenApiConfigurationOptions
{
public CustomDocumentFilters()
{
this.DocumentFilters.Add(new AddStatusEndpoint());
}
}

internal class AddStatusEndpoint : IDocumentFilter
{
private OpenApiPathItem StatusEndpoint(IHttpRequestDataObject req, OpenApiDocument document)
{
var pathItem = new OpenApiPathItem()
{
Servers = new List
{
new OpenApiServer
{
Url = $"{req.Scheme}://{req.Host}/",
Description = "The server hosting the Durable Functions API."
}
},
};

var getOperation = new OpenApiOperation
{
// implementation of a path
}
return pathItem;
}
public void Apply(IHttpRequestDataObject req, OpenApiDocument document)
{
document.Paths.Add("/runtime/webhooks/durabletask/instances/{instanceId}", StatusEndpoint(req, document));
}

```

Contributor guide

Open the contributing guide

Research direction

Start by tracing how IDocumentFilter changes to document.Paths and OpenApiPathItem are serialized into the final OpenAPI document. Reproduce the example with OpenApiPathItem.Servers, then compare the generated path item with the OpenAPI 3 specification; done means the path-level servers list appears in the output without breaking existing documents.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, csharp, openapi
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.