How to use XML comments with Minimal APIs?

[julioct]

The XML comments section describes how to generate an XML comments file using SwaggerGen options but all the examples are based in XML comments placed in MVC controller methods as opposed to minimal APIs.

How can I generate the summary element in the Swagger JSON file so the Swagger UI doc presents XML comments as documentation for each of the operations?

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 14fce65f-1337-58cb-2193-8d8e0e62792d
• Version Independent ID: 59222460-a971-e76e-4fe9-23d4d7d768ee
• Content: Get started with Swashbuckle and ASP.NET Core
• Content Source: aspnetcore/tutorials/getting-started-with-swashbuckle.md
• Product: aspnet-core
• Technology: aspnetcore-tutorials
• GitHub Login: @zuckerthoben
• Microsoft Alias: scaddie

[Rick-Anderson]

@rafikiassumani-msft How to use XML comments with Minimal APIs?

[serpent5]

@Rick-Anderson FYI, I saw David Fowler comment on Stack Overflow that this isn't supported.

[julioct]

@Rick-Anderson @serpent5 @davidfowl If XML comments aren't supported for minimal APIs, how can I get the same effect using any other available method? Looks like all I need is for the generated JSON to include a Summary element, as in the example on the page:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "parameters": [
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
},

Any way I can generate that Summary element using any other Minimal API available method?

[Rick-Anderson]

Thank you for contacting us. Due to a lack of activity on this discussion issue we're closing it in an effort to keep our backlog manageable. If you believe there is a concern which hasn't been addressed, please file a new issue.

[davidfowl]

cc @captainsafia

[captainsafia]

Any way I can generate that Summary element using any other Minimal API available method?

In the latest .NET 7 preview, you can use the new WithSummary description method on your endpoint or the WithOpenApi extension method. Documentation is here.

With regard to XML docs specifically, we are tracking this at dotnet/aspnetcore#39927. There are some workarounds in the linked issues.

[Rick-Anderson]

Thanks for contacting us. We believe that the question you've raised have been answered. If you still feel a need to continue the discussion, feel free to reopen it and add your comments.