Skip to content

Support for OpenAPI Description in [ProducesResponseType], [Produces], and [ProducesDefaultResponseType] Attributes #3456

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jun 13, 2025
Merged

Support for OpenAPI Description in [ProducesResponseType], [Produces], and [ProducesDefaultResponseType] Attributes #3456

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
a2ebe5c
Ensure Description property is obtained from attribute
Jun 13, 2025
5afe924
extra semicolon deleted
Jun 13, 2025
1844cf6
Changed the way description is obtained
Jun 13, 2025
983e0f2
typo
Jun 13, 2025
6a38ccc
typo tests
Jun 13, 2025
b395c3f
Apply suggestions from code review
martincostello Jun 13, 2025
312116c
Update test/WebSites/WebApi/EndPoints/XmlCommentsEndpoints.cs
martincostello Jun 13, 2025
6c48fc8
Update test/WebSites/WebApi/EndPoints/XmlCommentsEndpoints.cs
martincostello Jun 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,7 +272,7 @@ private async Task<OpenApiPaths> GeneratePathsAsync(
{
Operations = await operationsGenerator(document, group, schemaRepository)
});
};
}

return paths;
}
Expand Down Expand Up @@ -1064,9 +1064,16 @@ private OpenApiResponse GenerateResponse(
string statusCode,
ApiResponseType apiResponseType)
{
var description = ResponseDescriptionMap
string description = null;
#if NET10_0_OR_GREATER
description = apiResponseType.Description;
#endif
if (string.IsNullOrEmpty(description))
{
description = ResponseDescriptionMap
.FirstOrDefault((entry) => Regex.IsMatch(statusCode, entry.Key))
.Value;
}

var responseContentTypes = InferResponseContentTypes(apiDescription, apiResponseType);

Expand Down
112 changes: 112 additions & 0 deletions ...son_No_Startup_entryPointType=WebApi.Program_swaggerRequestUri=v1.DotNet10_0.verified.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -857,6 +857,118 @@
}
}
}
},
"/XmlComments/Car": {
"get": {
"tags": [
"Xml"
],
"summary": "Returns a specific product using asParameters record",
"parameters": [
{
"name": "Id",
"in": "query",
"description": "Uniquely identifies the product",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "Description",
"in": "query",
"description": "Describes the product",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "A Product",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
}
}
}
},
"/XmlComments/CarWithProduces": {
"get": {
"tags": [
"Xml"
],
"summary": "Returns a specific product With Produces attribute",
"parameters": [
{
"name": "id",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "A Product",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
}
}
}
},
"/XmlComments/CarWithProducesDefaultResponseType": {
"get": {
"tags": [
"Xml"
],
"summary": "Returns a specific product With ProducesDefaultResponseType attribute",
"parameters": [
{
"name": "id",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
},
"default": {
"description": "A Product",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
}
}
}
}
},
"components": {
Expand Down
112 changes: 112 additions & 0 deletions ....IntegrationTests/snapshots/VerifyTests.TypesAreRenderedCorrectly.DotNet10_0.verified.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -857,6 +857,118 @@
}
}
}
},
"/XmlComments/Car": {
"get": {
"tags": [
"Xml"
],
"summary": "Returns a specific product using asParameters record",
"parameters": [
{
"name": "Id",
"in": "query",
"description": "Uniquely identifies the product",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "Description",
"in": "query",
"description": "Describes the product",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "A Product",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
}
}
}
},
"/XmlComments/CarWithProduces": {
"get": {
"tags": [
"Xml"
],
"summary": "Returns a specific product With Produces attribute",
"parameters": [
{
"name": "id",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "A Product",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
}
}
}
},
"/XmlComments/CarWithProducesDefaultResponseType": {
"get": {
"tags": [
"Xml"
],
"summary": "Returns a specific product With ProducesDefaultResponseType attribute",
"parameters": [
{
"name": "id",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
},
"default": {
"description": "A Product",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
}
}
}
}
},
"components": {
Expand Down
32 changes: 31 additions & 1 deletion test/WebSites/WebApi/EndPoints/XmlCommentsEndpoints.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
namespace WebApi.EndPoints;
#if NET10_0_OR_GREATER
using Microsoft.AspNetCore.Mvc;
#endif
namespace WebApi.EndPoints;

/// <summary>
/// Class of Extensions to add XmlEndpoints
Expand All @@ -13,6 +16,11 @@ public static IEndpointRouteBuilder MapXmlCommentsEndpoints(this IEndpointRouteB
var group = app.MapGroup("/XmlComments").WithTags("Xml");

group.MapGet("/Car/{id}", GetProduct);
#if NET10_0_OR_GREATER
group.MapGet("Car", GetProductAsParameters);
group.MapGet("CarWithProduces",GetProductWithProduces);
group.MapGet("CarWithProducesDefaultResponseType",GetProductProducesDefaultResponseType);
#endif

return app;
}
Expand All @@ -23,6 +31,28 @@ public static IEndpointRouteBuilder MapXmlCommentsEndpoints(this IEndpointRouteB
/// <response code="200">A Product Id</response>
private static Product GetProduct(int id)
=> new() { Id = id, Description = "A product" };
#if NET10_0_OR_GREATER
/// <summary>
/// Returns a specific product using asParameters record
/// </summary>
[ProducesResponseType(typeof(Product),200, Description="A Product")]
private static Product GetProductAsParameters([AsParameters] Product productAsParameters)
=> productAsParameters;

/// <summary>
/// Returns a specific product With Produces attribute
/// </summary>
[Produces(typeof(Product), Description="A Product")]
private static Product GetProductWithProduces(int id)
=> new() { Id = id, Description = "A product" };

/// <summary>
/// Returns a specific product With ProducesDefaultResponseType attribute
/// </summary>
[ProducesDefaultResponseType(typeof(Product), Description="A Product")]
private static Product GetProductProducesDefaultResponseType(int id)
=> new() { Id = id, Description = "A product" };
#endif
}

/// <summary>
Expand Down