Skip to content

Commit ac7b877

Browse files
martincostelloSantiagoG14
martincostello
and
SantiagoG14
authored
Add description for OpenAPI schema references (#3860)
Apply description to properties using OpenAPI schema references when generating OpenAPI 3.1 documents. Resolves #3759. Co-authored-by: Santiago Garcia <70714718+santiagog14@users.noreply.github.com>
1 parent b2a9a92 commit ac7b877

14 files changed

+103
-14
lines changed

‎src/Swashbuckle.AspNetCore.SwaggerGen/SchemaGenerator/SchemaGenerator.cs‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -128,10 +128,10 @@ private IOpenApiSchema GenerateSchemaForMember(
128128
}
129129

130130
schema.ApplyValidationAttributes(customAttributes);
131-
132-
ApplyFilters(schema, modelType, schemaRepository, memberInfo: memberInfo);
133131
}
134132

133+
ApplyFilters(schema, modelType, schemaRepository, memberInfo: memberInfo);
134+
135135
return schema;
136136
}
137137

@@ -198,10 +198,10 @@ private IOpenApiSchema GenerateSchemaForParameter(
198198
{
199199
schema.ApplyRouteConstraints(routeInfo);
200200
}
201-
202-
ApplyFilters(schema, modelType, schemaRepository, parameterInfo: parameterInfo);
203201
}
204202

203+
ApplyFilters(schema, modelType, schemaRepository, parameterInfo: parameterInfo);
204+
205205
return schema;
206206
}
207207

@@ -213,13 +213,11 @@ private IOpenApiSchema GenerateSchemaForType(Type modelType, SchemaRepository sc
213213
? GeneratePolymorphicSchema(schemaRepository, knownTypesDataContracts)
214214
: GenerateConcreteSchema(dataContract, schemaRepository);
215215

216-
if (schema is not OpenApiSchemaReference)
216+
ApplyFilters(schema, modelType, schemaRepository);
217+
218+
if (Nullable.GetUnderlyingType(modelType) != null && schema is OpenApiSchema concrete)
217219
{
218-
ApplyFilters(schema, modelType, schemaRepository);
219-
if (Nullable.GetUnderlyingType(modelType) != null && schema is OpenApiSchema concrete)
220-
{
221-
SetNullable(concrete, true);
222-
}
220+
SetNullable(concrete, true);
223221
}
224222

225223
return schema;

‎src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SchemaRepository.cs‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,15 @@ public OpenApiSchemaReference AddDefinition(string schemaId, OpenApiSchema schem
4141
{
4242
Schemas.Add(schemaId, schema);
4343

44-
return new OpenApiSchemaReference(schemaId);
44+
return new(schemaId)
45+
{
46+
Default = schema.Default,
47+
Description = schema.Description,
48+
Deprecated = schema.Deprecated,
49+
Examples = schema.Examples,
50+
ReadOnly = schema.ReadOnly,
51+
Title = schema.Title,
52+
};
4553
}
4654

4755
public bool ReplaceSchemaId(Type schemaType, string replacementSchemaId)

‎test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,10 +295,12 @@
295295
"tags": [
296296
"DataAnnotations"
297297
],
298+
"summary": "Retrieves the list of appointments this week for the specified day.",
298299
"parameters": [
299300
{
300301
"in": "query",
301302
"name": "dayOfWeek",
303+
"description": "The day of week for which to get appointments.",
302304
"type": "string"
303305
}
304306
],
@@ -604,6 +606,7 @@
604606
{
605607
"in": "formData",
606608
"name": "logLevel",
609+
"description": "Summary for LogLevel",
607610
"type": "string"
608611
},
609612
{

‎test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,16 +20,19 @@
2020
"content": {
2121
"application/json": {
2222
"schema": {
23+
"description": "Represents a product",
2324
"$ref": "#/components/schemas/Product"
2425
}
2526
},
2627
"text/json": {
2728
"schema": {
29+
"description": "Represents a product",
2830
"$ref": "#/components/schemas/Product"
2931
}
3032
},
3133
"application/*+json": {
3234
"schema": {
35+
"description": "Represents a product",
3336
"$ref": "#/components/schemas/Product"
3437
}
3538
}
@@ -43,6 +46,7 @@
4346
"content": {
4447
"application/json": {
4548
"schema": {
49+
"description": "Represents a product",
4650
"$ref": "#/components/schemas/Product"
4751
}
4852
}
@@ -77,6 +81,7 @@
7781
"schema": {
7882
"type": "array",
7983
"items": {
84+
"description": "Represents a product",
8085
"$ref": "#/components/schemas/Product"
8186
}
8287
}
@@ -102,6 +107,7 @@
102107
"schema": {
103108
"type": "array",
104109
"items": {
110+
"description": "Represents a product",
105111
"$ref": "#/components/schemas/Product"
106112
}
107113
}
@@ -138,6 +144,7 @@
138144
"content": {
139145
"application/json": {
140146
"schema": {
147+
"description": "Represents a product",
141148
"$ref": "#/components/schemas/Product"
142149
}
143150
}
@@ -170,16 +177,19 @@
170177
"content": {
171178
"application/json": {
172179
"schema": {
180+
"description": "Represents a product",
173181
"$ref": "#/components/schemas/Product"
174182
}
175183
},
176184
"text/json": {
177185
"schema": {
186+
"description": "Represents a product",
178187
"$ref": "#/components/schemas/Product"
179188
}
180189
},
181190
"application/*+json": {
182191
"schema": {
192+
"description": "Represents a product",
183193
"$ref": "#/components/schemas/Product"
184194
}
185195
}
@@ -343,11 +353,14 @@
343353
"tags": [
344354
"DataAnnotations"
345355
],
356+
"summary": "Retrieves the list of appointments this week for the specified day.",
346357
"parameters": [
347358
{
348359
"name": "dayOfWeek",
349360
"in": "query",
361+
"description": "The day of week for which to get appointments.",
350362
"schema": {
363+
"description": "The day of the week.",
351364
"default": 4,
352365
"$ref": "#/components/schemas/DayOfWeek"
353366
}
@@ -749,6 +762,7 @@
749762
"description": "Summary for PhoneNumbers"
750763
},
751764
"logLevel": {
765+
"description": "Summary for LogLevel",
752766
"$ref": "#/components/schemas/LogLevel"
753767
},
754768
"formFile": {
@@ -1378,10 +1392,12 @@
13781392
"readOnly": true
13791393
},
13801394
"cartType": {
1395+
"description": "The type of the cart",
13811396
"default": 0,
13821397
"$ref": "#/components/schemas/CartType"
13831398
},
13841399
"basketType": {
1400+
"description": "The cart type",
13851401
"deprecated": true,
13861402
"$ref": "#/components/schemas/CartType"
13871403
}

‎test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -343,10 +343,12 @@
343343
"tags": [
344344
"DataAnnotations"
345345
],
346+
"summary": "Retrieves the list of appointments this week for the specified day.",
346347
"parameters": [
347348
{
348349
"name": "dayOfWeek",
349350
"in": "query",
351+
"description": "The day of week for which to get appointments.",
350352
"schema": {
351353
"$ref": "#/components/schemas/DayOfWeek"
352354
}

‎test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,10 +295,12 @@
295295
"tags": [
296296
"DataAnnotations"
297297
],
298+
"summary": "Retrieves the list of appointments this week for the specified day.",
298299
"parameters": [
299300
{
300301
"in": "query",
301302
"name": "dayOfWeek",
303+
"description": "The day of week for which to get appointments.",
302304
"type": "string"
303305
}
304306
],
@@ -604,6 +606,7 @@
604606
{
605607
"in": "formData",
606608
"name": "logLevel",
609+
"description": "Summary for LogLevel",
607610
"type": "string"
608611
},
609612
{

‎test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=3.1.verified.txt‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,16 +20,19 @@
2020
"content": {
2121
"application/json": {
2222
"schema": {
23+
"description": "Represents a product",
2324
"$ref": "#/components/schemas/Product"
2425
}
2526
},
2627
"text/json": {
2728
"schema": {
29+
"description": "Represents a product",
2830
"$ref": "#/components/schemas/Product"
2931
}
3032
},
3133
"application/*+json": {
3234
"schema": {
35+
"description": "Represents a product",
3336
"$ref": "#/components/schemas/Product"
3437
}
3538
}
@@ -43,6 +46,7 @@
4346
"content": {
4447
"application/json": {
4548
"schema": {
49+
"description": "Represents a product",
4650
"$ref": "#/components/schemas/Product"
4751
}
4852
}
@@ -77,6 +81,7 @@
7781
"schema": {
7882
"type": "array",
7983
"items": {
84+
"description": "Represents a product",
8085
"$ref": "#/components/schemas/Product"
8186
}
8287
}
@@ -102,6 +107,7 @@
102107
"schema": {
103108
"type": "array",
104109
"items": {
110+
"description": "Represents a product",
105111
"$ref": "#/components/schemas/Product"
106112
}
107113
}
@@ -138,6 +144,7 @@
138144
"content": {
139145
"application/json": {
140146
"schema": {
147+
"description": "Represents a product",
141148
"$ref": "#/components/schemas/Product"
142149
}
143150
}
@@ -170,16 +177,19 @@
170177
"content": {
171178
"application/json": {
172179
"schema": {
180+
"description": "Represents a product",
173181
"$ref": "#/components/schemas/Product"
174182
}
175183
},
176184
"text/json": {
177185
"schema": {
186+
"description": "Represents a product",
178187
"$ref": "#/components/schemas/Product"
179188
}
180189
},
181190
"application/*+json": {
182191
"schema": {
192+
"description": "Represents a product",
183193
"$ref": "#/components/schemas/Product"
184194
}
185195
}
@@ -343,11 +353,14 @@
343353
"tags": [
344354
"DataAnnotations"
345355
],
356+
"summary": "Retrieves the list of appointments this week for the specified day.",
346357
"parameters": [
347358
{
348359
"name": "dayOfWeek",
349360
"in": "query",
361+
"description": "The day of week for which to get appointments.",
350362
"schema": {
363+
"description": "The day of the week.",
351364
"default": 4,
352365
"$ref": "#/components/schemas/DayOfWeek"
353366
}
@@ -749,6 +762,7 @@
749762
"description": "Summary for PhoneNumbers"
750763
},
751764
"logLevel": {
765+
"description": "Summary for LogLevel",
752766
"$ref": "#/components/schemas/LogLevel"
753767
},
754768
"formFile": {
@@ -1378,10 +1392,12 @@
13781392
"readOnly": true
13791393
},
13801394
"cartType": {
1395+
"description": "The type of the cart",
13811396
"default": 0,
13821397
"$ref": "#/components/schemas/CartType"
13831398
},
13841399
"basketType": {
1400+
"description": "The cart type",
13851401
"deprecated": true,
13861402
"$ref": "#/components/schemas/CartType"
13871403
}

‎test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -343,10 +343,12 @@
343343
"tags": [
344344
"DataAnnotations"
345345
],
346+
"summary": "Retrieves the list of appointments this week for the specified day.",
346347
"parameters": [
347348
{
348349
"name": "dayOfWeek",
349350
"in": "query",
351+
"description": "The day of week for which to get appointments.",
350352
"schema": {
351353
"$ref": "#/components/schemas/DayOfWeek"
352354
}

‎test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=2.0.verified.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,10 +295,12 @@
295295
"tags": [
296296
"DataAnnotations"
297297
],
298+
"summary": "Retrieves the list of appointments this week for the specified day.",
298299
"parameters": [
299300
{
300301
"in": "query",
301302
"name": "dayOfWeek",
303+
"description": "The day of week for which to get appointments.",
302304
"type": "string"
303305
}
304306
],
@@ -604,6 +606,7 @@
604606
{
605607
"in": "formData",
606608
"name": "logLevel",
609+
"description": "Summary for LogLevel",
607610
"type": "string"
608611
},
609612
{

0 commit comments

Comments
 (0)