[OpenAPI] XML Comments not translated to OpenApi json

[kevin-shelaga]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

If you have xml comments with multiple response codes, only the first one is translated.

    /// <summary>
    /// Retrieves a specific project board by ID.
    /// </summary>
    /// <param name="id">The ID of the project board to retrieve.</param>
    /// <returns>The requested project board.</returns>
    /// <response code="200">Returns the requested project board.</response>
    /// <response code="404">If the project board is not found.</response>
    public static IResult GetProjectBoardById(int id)
    {
        var board = Boards.FirstOrDefault(b => b.Id == id);
        if (board == null)
        {
            return Results.NotFound();
        }
        return Results.Ok(board);
    }

{
  "openapi": "3.1.1",
  "info": {
    "title": "Api | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:5052"
    }
  ],
  "paths": {
    "/api/projectboards": {
      "get": {
        "tags": [
          "Project Boards"
        ],
        "summary": "Retrieves all project boards.",
        "responses": {
          "200": {
            "description": "Returns the list of project boards."
          }
        }
      },
      "post": {
        "tags": [
          "Project Boards"
        ],
        "summary": "Creates a new project board.",
        "requestBody": {
          "description": "The project board to create.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProjectBoard"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/projectboards/{id}": {
      "get": {
        "tags": [
          "Project Boards"
        ],
        "summary": "Retrieves a specific project board by ID.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The ID of the project board to retrieve.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the requested project board."
          }
        }
      },
      "put": {
        "tags": [
          "Project Boards"
        ],
        "summary": "Updates an existing project board.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The ID of the project board to update.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "requestBody": {
          "description": "The updated project board data.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProjectBoard"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "delete": {
        "tags": [
          "Project Boards"
        ],
        "summary": "Deletes a project board.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The ID of the project board to delete.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/projectboards/{boardId}/todos": {
      "get": {
        "tags": [
          "Todos"
        ],
        "summary": "Retrieves all todos for a specific project board. INFOMEDIA",
        "parameters": [
          {
            "name": "boardId",
            "in": "path",
            "description": "The ID of the project board.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the list of todos."
          }
        }
      },
      "post": {
        "tags": [
          "Todos"
        ],
        "summary": "Creates a new todo within a project board.",
        "parameters": [
          {
            "name": "boardId",
            "in": "path",
            "description": "The ID of the project board.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "requestBody": {
          "description": "The todo to create.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Todo"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/projectboards/{boardId}/todos/{id}": {
      "get": {
        "tags": [
          "Todos"
        ],
        "summary": "Retrieves a specific todo by ID within a project board.",
        "parameters": [
          {
            "name": "boardId",
            "in": "path",
            "description": "The ID of the project board.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          },
          {
            "name": "id",
            "in": "path",
            "description": "The ID of the todo to retrieve.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the requested todo."
          }
        }
      },
      "put": {
        "tags": [
          "Todos"
        ],
        "summary": "Updates an existing todo within a project board.",
        "parameters": [
          {
            "name": "boardId",
            "in": "path",
            "description": "The ID of the project board.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          },
          {
            "name": "id",
            "in": "path",
            "description": "The ID of the todo to update.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "requestBody": {
          "description": "The updated todo data.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Todo"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      },
      "delete": {
        "tags": [
          "Todos"
        ],
        "summary": "Deletes a todo from a project board.",
        "parameters": [
          {
            "name": "boardId",
            "in": "path",
            "description": "The ID of the project board.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          },
          {
            "name": "id",
            "in": "path",
            "description": "The ID of the todo to delete.",
            "required": true,
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProjectBoard": {
        "type": "object",
        "properties": {
          "id": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "description": "Unique identifier for the project board.",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "description": "The name of the project board."
          },
          "description": {
            "type": [
              "null",
              "string"
            ],
            "description": "A description of the project board and its purpose."
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the project board was created.",
            "format": "date-time"
          },
          "todos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Todo"
            },
            "description": "The collection of todos associated with this project board."
          }
        },
        "description": "Represents a project board containing todos and related information."
      },
      "Todo": {
        "type": "object",
        "properties": {
          "id": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "description": "Unique identifier for the todo item.",
            "format": "int32"
          },
          "title": {
            "type": "string",
            "description": "The title or brief description of the todo."
          },
          "description": {
            "type": [
              "null",
              "string"
            ],
            "description": "A detailed description of the todo item."
          },
          "isComplete": {
            "type": "boolean",
            "description": "Indicates whether the todo has been completed."
          },
          "priority": {
            "$ref": "#/components/schemas/TodoPriority"
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the todo was created.",
            "format": "date-time"
          },
          "dueDate": {
            "type": [
              "null",
              "string"
            ],
            "description": "The date when the todo is due to be completed.",
            "format": "date-time"
          },
          "projectBoardId": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "description": "The ID of the project board this todo belongs to.",
            "format": "int32"
          }
        },
        "description": "Represents a todo item within a project board."
      },
      "TodoPriority": {
        "type": "integer",
        "description": "Represents the priority level of a todo item."
      }
    }
  },
  "tags": [
    {
      "name": "Project Boards"
    },
    {
      "name": "Todos"
    }
  ]
}

Expected Behavior

All responses should be written to the json

Steps To Reproduce

full reproduction from example in official docs https://github.com/captainsafia/aspnet-openapi-xml/blob/670f571f6d22559e728f3e0e6046100761dfcb0a/api/ProjectBoardApis.cs

Exceptions (if any)

No response

.NET Version

dotnet 10 preview 2 and preview 3

Anything else?

No response

[captainsafia]

@kevin-shelaga Thanks for filing this issue!

I think this is actually a bug in the sample app I wrote and not in the XML generator support. I used IResult instead of TypedResults<Ok, NotFound> in the sample app so the system is inferring the default 200 OK status code and not seeing the 404 Not Found at all. Changing the type signature of the method should fix this.

Would you be interested in submitting a PR to the other repo to fix this?

[kevin-shelaga]

@captainsafia sure, I can take a look at that.

I'm trying to understand how xml comments have been implemented and it doesn't seem like you can use controllers or async. It won't "just work" when migrating from swashbuckle.

Is this by design or are there still parts missing to the full implementation?

[captainsafia]

I'm trying to understand how xml comments have been implemented and it doesn't seem like you can use controllers or async. It won't "just work" when migrating from swashbuckle.

There's nothing that prohibits the tool from working with controllers and/or asynchronous code paths. Did you try it with those and not have luck?

[kevin-shelaga]

Yes, essentially I had everything working with controllers for a few years. Upgraded to .net 10 preview 3. Scalar comes up, comments are generated into xml but the openapi json is basically the bare minimum bootstrap with path names and params with no descriptions etc.

I slowly pulled out all routes one by one until I had a simple bool route. Still not generated. It wasn't until I stripped everything back to follow the pattern you used in the demo did finally the json get updated.

[captainsafia]

Yes, essentially I had everything working with controllers for a few years. Upgraded to .net 10 preview 3.

When you say upgraded to ".NET 10 Preview 3" do you mean that you're using the Microsoft.AspNetCore.OpenApi package as well?

Do you have a minimal example of an controller class/method with the XML docs that you'd expect to see happening?

[kevin-shelaga]

Yes. Updated open api package as well. Literally exactly like your demo is what I knocked it down to but 1 controller and still nothing. When i copied the controller code out to a static method (like the demo) added those extra map.get etc, the json was updated. Will setup a demo repo

[desjoerd]

Ok, got the same issue, after some debugging I found that the MemberKey does not match from the Source Generator with runtime the moment the Method is async and returns Task<Results<>>.

Another thing I noticed when removing async it will completly breakdown (although, using Task without async is a pain and would probably not happen that fast):

OpenApiXmlCommentSupport.generated.cs(189,167): error CS0308: The non-generic type 'Task' cannot be used with type arguments

Example which does not compile:

    internal static void MapSummary(this IEndpointRouteBuilder routes)
    {
        routes.MapGet("/endpoint-with-summary", Handler);
    }

    /// <summary>
    /// This should be in the summary
    /// </summary>
    private static Task<Results<Ok<string>, NotFound>> Handler(
        CancellationToken cancellationToken)
    {
        return Task.FromResult<Results<Ok<string>, NotFound>>(TypedResults.Ok("Does not compile"));
    }

Example which has different keys
On runtime it's Task<Results<Ok<string>, NotFound>>
In the source Generator it's Results<,>:

    internal static void MapSummary(this IEndpointRouteBuilder routes)
    {
        routes.MapGet("/endpoint-with-summary", Handler);
    }

    /// <summary>
    /// This should be in the summary
    /// </summary>
    private static async Task<Results<Ok<string>, NotFound>> Handler(
        CancellationToken cancellationToken)
    {
        return TypedResults.Ok("Different MethodKey");
    }

_cache.Add(new MemberKey(typeof(global::Unlocked.Api.Endpoints.GetSummary), MemberType.Method, "Handler", typeof(global::Microsoft.AspNetCore.Http.HttpResults.Results<,>), [typeof(global::System.Threading.CancellationToken)]), new XmlComment(@"This should be in the summary", null, null, null, null, false, null, null, null));

Working example (without async):

    internal static void MapSummary(this IEndpointRouteBuilder routes)
    {
        routes.MapGet("/endpoint-with-summary", Handler);
    }

    /// <summary>
    /// This should be in the summary
    /// </summary>
    private static Results<Ok<string>, NotFound> Handler(
        CancellationToken cancellationToken)
    {
        return TypedResults.Ok("Works");
    }

Package versions:

    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.3.25172.1" />
    <PackageVersion Include="Microsoft.Extensions.ApiDescription.Server" Version="10.0.0-preview.3.25172.1" />

[desjoerd]

    /// <summary>
    /// Retrieves a specific project board by ID.
    /// </summary>
    /// <param name="id">The ID of the project board to retrieve.</param>
    /// <returns>The requested project board.</returns>
    /// <response code="200">Returns the requested project board.</response>
    /// <response code="404">If the project board is not found.</response>
    public static IResult GetProjectBoardById(int id)
    {
        var board = Boards.FirstOrDefault(b => b.Id == id);
        if (board == null)
        {
            return Results.NotFound();
        }
        return Results.Ok(board);
    }

@kevin-shelaga On thing to note on returning IResult. That doesn't provide any metadata to the ApiExplorer. It just says, this can be any response In openapi having a response is "required" so it defaults to a simple "200 OK". That's what Results<,> is for and the TypedResults helper.

You will see all those types implement IEndpointMetadataProvider which contains a static method PopulateMetadata.
For example here is the one for Ok<TValue>

    static void IEndpointMetadataProvider.PopulateMetadata(MethodInfo method, EndpointBuilder builder)
    {
        ArgumentNullException.ThrowIfNull(method);
        ArgumentNullException.ThrowIfNull(builder);

        builder.Metadata.Add(ProducesResponseTypeMetadata.CreateUnvalidated(typeof(TValue), StatusCodes.Status200OK, ContentTypeConstants.ApplicationJsonContentTypes));
    }

PopulateMetadata is only called when the return type is a type directly implementing it. So you need to return Concrete types in your endpoints to let this work. If you want to return multiple different types of responses you can use Results<,> which also implements IEndpointMetadataProvider and calls it on the Concrete types of the generic parameters.

[kevin-shelaga]

Thanks @desjoerd i have been playing with that exact same thing this weekend. So far I can still only get a 200 and 401 to return in the open API json despite listing 200, 400, 401, and 500 while setting the following

/// <response code="200">Returns new access and refresh tokens.</response>
/// <response code="400">If the refresh token is invalid, expired, revoked, or the request is malformed.</response>
/// <response code="401">If client authentication fails (invalid client_id/client_secret).</response>
/// <response code="429">Too Many Requests (if rate limiting is applied).</response>
/// <response code="500">If an unexpected server error occurs.</response>
public static Results<Ok<TokenResponse>, BadRequest<string>, UnauthorizedHttpResult, ProblemHttpResult> RefreshToken(string refresh_token)

[desjoerd]

I assume you're coming from Nswag or Swashbuckle. They work differently regarding the comments. At least NSwag. They add responses based on comments as an extra source. ASP.NET Core openapi only uses comments to enrich, as it's completely based on the ApiExplorer and that only sees Metadata (not comments).

If you want to add the 429 for example you should put that as a .Produces on the Route builder

[kevin-shelaga]

Interesting, does this apply to controllers too? How would I use xml comments with a controller implementation?