Skip to content

Commit a96ed23

Browse files
commonsensesoftwarecommonsensesoftware
committed
Add support to control how the OpenAPI document description is rendered and emit policy links in the x-api-versioning extension.
1 parent 3f3eeef commit a96ed23

File tree

7 files changed

+490
-17
lines changed

7 files changed

+490
-17
lines changed

‎src/AspNetCore/WebApi/src/Asp.Versioning.OpenApi/Asp.Versioning.OpenApi.csproj‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
</ItemGroup>
2121

2222
<ItemGroup>
23-
<ProjectReference Include="..\Asp.Versioning.Mvc.ApiExplorer\Asp.Versioning.Mvc.ApiExplorer.csproj" />
23+
<ProjectReference Include="..\Asp.Versioning.Mvc.ApiExplorer\Asp.Versioning.Mvc.ApiExplorer.csproj" />
2424
</ItemGroup>
2525

2626
</Project>

‎src/AspNetCore/WebApi/src/Asp.Versioning.OpenApi/ConfigureOpenApiOptions.cs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ namespace Asp.Versioning.OpenApi;
1616
internal sealed class ConfigureOpenApiOptions(
1717
IHostEnvironment environment,
1818
IApiVersionDescriptionProviderFactory factory,
19+
IOptions<OpenApiDocumentDescriptionOptions> descriptionOptions,
1920
[FromKeyedServices( typeof( ApiVersion ) )] Action<ApiVersionDescription, OpenApiOptions> configure )
2021
: IConfigureNamedOptions<OpenApiOptions>
2122
{
@@ -51,7 +52,7 @@ public void Configure( string? name, OpenApiOptions options )
5152
continue;
5253
}
5354

54-
var apiExplorer = new ApiExplorerTransformer( description );
55+
var apiExplorer = new ApiExplorerTransformer( description, descriptionOptions );
5556

5657
options.SetDocumentName( description.GroupName );
5758
options.AddDocumentTransformer( apiExplorer );

‎src/AspNetCore/WebApi/src/Asp.Versioning.OpenApi/DependencyInjection/IApiVersioningBuilderExtensions.cs‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,10 +53,53 @@ public IApiVersioningBuilder AddOpenApi( Action<ApiVersionDescription, OpenApiOp
5353

5454
return builder;
5555
}
56+
57+
/// <summary>
58+
/// Adds OpenAPI support for API versioning.
59+
/// </summary>
60+
/// <param name="descriptionOptions">The function used to configure the target
61+
/// <see cref="OpenApiDocumentDescriptionOptions">title options</see>.</param>
62+
/// <returns>The original <see cref="IApiVersioningBuilder">builder</see>.</returns>
63+
public IApiVersioningBuilder AddOpenApi( Action<OpenApiDocumentDescriptionOptions> descriptionOptions )
64+
{
65+
ArgumentNullException.ThrowIfNull( builder );
66+
67+
var services = builder.Services;
68+
69+
AddOpenApiServices( services );
70+
services.Configure( descriptionOptions );
71+
services.TryAddKeyedTransient( typeof( ApiVersion ), NoOptions );
72+
73+
return builder;
74+
}
75+
76+
/// <summary>
77+
/// Adds OpenAPI support for API versioning.
78+
/// </summary>
79+
/// <param name="configureOptions">The function used to configure the target
80+
/// <see cref="OpenApiOptions">OpenAPI options</see>.</param>
81+
/// <param name="descriptionOptions">The function used to configure the target
82+
/// <see cref="OpenApiDocumentDescriptionOptions">title options</see>.</param>
83+
/// <returns>The original <see cref="IApiVersioningBuilder">builder</see>.</returns>
84+
public IApiVersioningBuilder AddOpenApi(
85+
Action<ApiVersionDescription, OpenApiOptions> configureOptions,
86+
Action<OpenApiDocumentDescriptionOptions> descriptionOptions )
87+
{
88+
ArgumentNullException.ThrowIfNull( builder );
89+
90+
var services = builder.Services;
91+
92+
AddOpenApiServices( services );
93+
services.Configure( descriptionOptions );
94+
services.TryAddKeyedTransient( typeof( ApiVersion ), ( _, _ ) => configureOptions );
95+
96+
return builder;
97+
}
5698
}
5799

58100
private static void AddOpenApiServices( IServiceCollection services )
59101
{
102+
services.AddOptions<OpenApiDocumentDescriptionOptions>();
60103
services.Add( Singleton<ConfigureOpenApiOptions, ConfigureOpenApiOptions>() );
61104
services.TryAddEnumerable( Singleton<IConfigureOptions<OpenApiOptions>, ConfigureOpenApiOptions>( static sp => sp.GetRequiredService<ConfigureOpenApiOptions>() ) );
62105

‎src/AspNetCore/WebApi/src/Asp.Versioning.OpenApi/OpenApiDocumentDescriptionOptions.cs‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// Copyright (c) .NET Foundation and contributors. All rights reserved.
2+
3+
namespace Asp.Versioning.OpenApi;
4+
5+
using System.Globalization;
6+
using System.Text;
7+
8+
/// <summary>
9+
/// Represents the options used to format the OpenAPI document title.
10+
/// </summary>
11+
public class OpenApiDocumentDescriptionOptions
12+
{
13+
private static CompositeFormat? sunsetNoticeFormat;
14+
15+
/// <summary>
16+
/// Gets or sets a value indicating whether API versioning policy links are hidden.
17+
/// </summary>
18+
/// <value>True if API versioning policy links are hidden; otherwise, false. The default value is
19+
/// <c>false</c>.</value>
20+
/// <remarks>Only API versioning policy links with the media type <c>text/html</c> will be shown.</remarks>
21+
public bool HidePolicyLinks { get; set; }
22+
23+
/// <summary>
24+
/// Gets or sets the function used to generate the API versioning deprecation notice based on the provided policy.
25+
/// </summary>
26+
/// <value>The <see cref="Func{T, TResult}">function</see> used to generate the deprecation notice.</value>
27+
/// <remarks>If the function generates a <c>null</c> or empty message, then no notice is displayed.</remarks>
28+
public Func<string?> DeprecationNotice { get; set; } = () => SR.DeprecationNoticeFormat;
29+
30+
/// <summary>
31+
/// Gets or sets the function used to generate the API versioning sunset notice based on the provided policy.
32+
/// </summary>
33+
/// <value>The <see cref="Func{T, TResult}">function</see> used to generate the sunset notice.</value>
34+
/// <remarks>If the function generates a <c>null</c> or empty message, then no notice is displayed.</remarks>
35+
public Func<SunsetPolicy, string?> SunsetNotice { get; set; } = DefaultSunsetNotice;
36+
37+
private static string? DefaultSunsetNotice( SunsetPolicy policy )
38+
{
39+
if ( policy.Date is { } when )
40+
{
41+
sunsetNoticeFormat ??= CompositeFormat.Parse( SR.SunsetNoticeFormat );
42+
return string.Format( CultureInfo.CurrentCulture, sunsetNoticeFormat, when );
43+
}
44+
45+
return default;
46+
}
47+
}

‎src/AspNetCore/WebApi/src/Asp.Versioning.OpenApi/SR.Designer.cs‎

Lines changed: 81 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/AspNetCore/WebApi/src/Asp.Versioning.OpenApi/SR.resx‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<root>
3+
<!--
4+
Microsoft ResX Schema
5+
6+
Version 2.0
7+
8+
The primary goals of this format is to allow a simple XML format
9+
that is mostly human readable. The generation and parsing of the
10+
various data types are done through the TypeConverter classes
11+
associated with the data types.
12+
13+
Example:
14+
15+
... ado.net/XML headers & schema ...
16+
<resheader name="resmimetype">text/microsoft-resx</resheader>
17+
<resheader name="version">2.0</resheader>
18+
<resheader name="reader">System.Resources.ResXResourceReader, System.Windows.Forms, ...</resheader>
19+
<resheader name="writer">System.Resources.ResXResourceWriter, System.Windows.Forms, ...</resheader>
20+
<data name="Name1"><value>this is my long string</value><comment>this is a comment</comment></data>
21+
<data name="Color1" type="System.Drawing.Color, System.Drawing">Blue</data>
22+
<data name="Bitmap1" mimetype="application/x-microsoft.net.object.binary.base64">
23+
<value>[base64 mime encoded serialized .NET Framework object]</value>
24+
</data>
25+
<data name="Icon1" type="System.Drawing.Icon, System.Drawing" mimetype="application/x-microsoft.net.object.bytearray.base64">
26+
<value>[base64 mime encoded string representing a byte array form of the .NET Framework object]</value>
27+
<comment>This is a comment</comment>
28+
</data>
29+
30+
There are any number of "resheader" rows that contain simple
31+
name/value pairs.
32+
33+
Each data row contains a name, and value. The row also contains a
34+
type or mimetype. Type corresponds to a .NET class that support
35+
text/value conversion through the TypeConverter architecture.
36+
Classes that don't support this are serialized and stored with the
37+
mimetype set.
38+
39+
The mimetype is used for serialized objects, and tells the
40+
ResXResourceReader how to depersist the object. This is currently not
41+
extensible. For a given mimetype the value must be set accordingly:
42+
43+
Note - application/x-microsoft.net.object.binary.base64 is the format
44+
that the ResXResourceWriter will generate, however the reader can
45+
read any of the formats listed below.
46+
47+
mimetype: application/x-microsoft.net.object.binary.base64
48+
value : The object must be serialized with
49+
: System.Runtime.Serialization.Formatters.Binary.BinaryFormatter
50+
: and then encoded with base64 encoding.
51+
52+
mimetype: application/x-microsoft.net.object.soap.base64
53+
value : The object must be serialized with
54+
: System.Runtime.Serialization.Formatters.Soap.SoapFormatter
55+
: and then encoded with base64 encoding.
56+
57+
mimetype: application/x-microsoft.net.object.bytearray.base64
58+
value : The object must be serialized into a byte array
59+
: using a System.ComponentModel.TypeConverter
60+
: and then encoded with base64 encoding.
61+
-->
62+
<xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
63+
<xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
64+
<xsd:element name="root" msdata:IsDataSet="true">
65+
<xsd:complexType>
66+
<xsd:choice maxOccurs="unbounded">
67+
<xsd:element name="metadata">
68+
<xsd:complexType>
69+
<xsd:sequence>
70+
<xsd:element name="value" type="xsd:string" minOccurs="0" />
71+
</xsd:sequence>
72+
<xsd:attribute name="name" use="required" type="xsd:string" />
73+
<xsd:attribute name="type" type="xsd:string" />
74+
<xsd:attribute name="mimetype" type="xsd:string" />
75+
<xsd:attribute ref="xml:space" />
76+
</xsd:complexType>
77+
</xsd:element>
78+
<xsd:element name="assembly">
79+
<xsd:complexType>
80+
<xsd:attribute name="alias" type="xsd:string" />
81+
<xsd:attribute name="name" type="xsd:string" />
82+
</xsd:complexType>
83+
</xsd:element>
84+
<xsd:element name="data">
85+
<xsd:complexType>
86+
<xsd:sequence>
87+
<xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
88+
<xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
89+
</xsd:sequence>
90+
<xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
91+
<xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
92+
<xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
93+
<xsd:attribute ref="xml:space" />
94+
</xsd:complexType>
95+
</xsd:element>
96+
<xsd:element name="resheader">
97+
<xsd:complexType>
98+
<xsd:sequence>
99+
<xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
100+
</xsd:sequence>
101+
<xsd:attribute name="name" type="xsd:string" use="required" />
102+
</xsd:complexType>
103+
</xsd:element>
104+
</xsd:choice>
105+
</xsd:complexType>
106+
</xsd:element>
107+
</xsd:schema>
108+
<resheader name="resmimetype">
109+
<value>text/microsoft-resx</value>
110+
</resheader>
111+
<resheader name="version">
112+
<value>2.0</value>
113+
</resheader>
114+
<resheader name="reader">
115+
<value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
116+
</resheader>
117+
<resheader name="writer">
118+
<value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
119+
</resheader>
120+
<data name="DeprecationNoticeFormat" xml:space="preserve">
121+
<value>This API version has been deprecated.</value>
122+
</data>
123+
<data name="SunsetNoticeFormat" xml:space="preserve">
124+
<value>The API will be sunset on {0:d}.</value>
125+
<comment>0 = the sunset date and time</comment>
126+
</data>
127+
</root>

0 commit comments

Comments
 (0)