diff --git a/src/Tingle.AspNetCore.Swagger/Extensions/IServiceCollectionExtensions.cs b/src/Tingle.AspNetCore.Swagger/Extensions/IServiceCollectionExtensions.cs index 7776771..d31ef35 100644 --- a/src/Tingle.AspNetCore.Swagger/Extensions/IServiceCollectionExtensions.cs +++ b/src/Tingle.AspNetCore.Swagger/Extensions/IServiceCollectionExtensions.cs @@ -11,16 +11,6 @@ namespace Microsoft.Extensions.DependencyInjection; /// public static class IServiceCollectionExtensions { - /// - /// Adds conversion of XML comments extracted for Swagger to markdown. - /// - /// the service collection to use - /// - public static IServiceCollection AddSwaggerXmlToMarkdown(this IServiceCollection services) - { - return services.AddTransient, ConfigureSwaggerGenXmlToMarkdown>(); - } - /// /// Adds enum descriptions. /// This should be called after all XML documents have been added. diff --git a/src/Tingle.AspNetCore.Swagger/Filters/ConfigureSwaggerGenXmlToMarkdown.cs b/src/Tingle.AspNetCore.Swagger/Filters/ConfigureSwaggerGenXmlToMarkdown.cs deleted file mode 100644 index 5f06eef..0000000 --- a/src/Tingle.AspNetCore.Swagger/Filters/ConfigureSwaggerGenXmlToMarkdown.cs +++ /dev/null @@ -1,29 +0,0 @@ -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Options; -using Swashbuckle.AspNetCore.SwaggerGen; -using Tingle.AspNetCore.Swagger.Filters.Documents; -using Tingle.AspNetCore.Swagger.Filters.Operations; -using Tingle.AspNetCore.Swagger.Filters.Parameters; -using Tingle.AspNetCore.Swagger.Filters.RequestBodies; -using Tingle.AspNetCore.Swagger.Filters.Schemas; - -namespace Tingle.AspNetCore.Swagger.Filters; - -/// -/// An for -/// that adds filters which convert XML comments to Markdown. -/// This should happen at the last step of configuration so that the comments are already pulled. -/// Hence why the use of . -/// -internal class ConfigureSwaggerGenXmlToMarkdown : IPostConfigureOptions -{ - /// - public void PostConfigure(string? name, SwaggerGenOptions options) - { - options.ParameterFilter(); - options.RequestBodyFilter(); - options.OperationFilter(); - options.SchemaFilter(); - options.DocumentFilter(); - } -} diff --git a/src/Tingle.AspNetCore.Swagger/Filters/Documents/MarkdownDocumentFilter.cs b/src/Tingle.AspNetCore.Swagger/Filters/Documents/MarkdownDocumentFilter.cs deleted file mode 100644 index c292acf..0000000 --- a/src/Tingle.AspNetCore.Swagger/Filters/Documents/MarkdownDocumentFilter.cs +++ /dev/null @@ -1,21 +0,0 @@ -using Microsoft.OpenApi.Models; -using Swashbuckle.AspNetCore.SwaggerGen; - -namespace Tingle.AspNetCore.Swagger.Filters.Documents; - -/// -/// An that converts XML comments to Markdown. -/// -public class MarkdownDocumentFilter : IDocumentFilter -{ - /// - public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context) - { - if (swaggerDoc.Tags is null) return; - - foreach (var t in swaggerDoc.Tags) - { - t.Description = XmlCommentsHelper.ToMarkdown(t.Description); - } - } -} diff --git a/src/Tingle.AspNetCore.Swagger/Filters/Operations/MarkdownOperationFilter.cs b/src/Tingle.AspNetCore.Swagger/Filters/Operations/MarkdownOperationFilter.cs deleted file mode 100644 index 69f28e8..0000000 --- a/src/Tingle.AspNetCore.Swagger/Filters/Operations/MarkdownOperationFilter.cs +++ /dev/null @@ -1,22 +0,0 @@ -using Microsoft.OpenApi.Models; -using Swashbuckle.AspNetCore.SwaggerGen; - -namespace Tingle.AspNetCore.Swagger.Filters.Operations; - -/// -/// An that converts XML comments to Markdown. -/// -public class MarkdownOperationFilter : IOperationFilter -{ - /// - public void Apply(OpenApiOperation operation, OperationFilterContext context) - { - operation.Summary = XmlCommentsHelper.ToMarkdown(operation.Summary); - operation.Description = XmlCommentsHelper.ToMarkdown(operation.Description); - foreach (var kvp in operation.Responses) - { - var response = kvp.Value; - response.Description = XmlCommentsHelper.ToMarkdown(response.Description); - } - } -} diff --git a/src/Tingle.AspNetCore.Swagger/Filters/Parameters/MarkdownParameterFilter.cs b/src/Tingle.AspNetCore.Swagger/Filters/Parameters/MarkdownParameterFilter.cs deleted file mode 100644 index 9d26e35..0000000 --- a/src/Tingle.AspNetCore.Swagger/Filters/Parameters/MarkdownParameterFilter.cs +++ /dev/null @@ -1,16 +0,0 @@ -using Microsoft.OpenApi.Models; -using Swashbuckle.AspNetCore.SwaggerGen; - -namespace Tingle.AspNetCore.Swagger.Filters.Parameters; - -/// -/// An that converts XML comments to Markdown. -/// -public class MarkdownParameterFilter : IParameterFilter -{ - /// - public void Apply(OpenApiParameter parameter, ParameterFilterContext context) - { - parameter.Description = XmlCommentsHelper.ToMarkdown(parameter.Description); - } -} diff --git a/src/Tingle.AspNetCore.Swagger/Filters/RequestBodies/MarkdownRequestBodyFilter.cs b/src/Tingle.AspNetCore.Swagger/Filters/RequestBodies/MarkdownRequestBodyFilter.cs deleted file mode 100644 index 9bb99ec..0000000 --- a/src/Tingle.AspNetCore.Swagger/Filters/RequestBodies/MarkdownRequestBodyFilter.cs +++ /dev/null @@ -1,16 +0,0 @@ -using Microsoft.OpenApi.Models; -using Swashbuckle.AspNetCore.SwaggerGen; - -namespace Tingle.AspNetCore.Swagger.Filters.RequestBodies; - -/// -/// An that converts XML comments to Markdown. -/// -public class MarkdownRequestBodyFilter : IRequestBodyFilter -{ - /// - public void Apply(OpenApiRequestBody requestBody, RequestBodyFilterContext context) - { - requestBody.Description = XmlCommentsHelper.ToMarkdown(requestBody.Description); - } -} diff --git a/src/Tingle.AspNetCore.Swagger/Filters/Schemas/EnumDescriptionsSchemaFilter.cs b/src/Tingle.AspNetCore.Swagger/Filters/Schemas/EnumDescriptionsSchemaFilter.cs index 0038f7d..de89be6 100644 --- a/src/Tingle.AspNetCore.Swagger/Filters/Schemas/EnumDescriptionsSchemaFilter.cs +++ b/src/Tingle.AspNetCore.Swagger/Filters/Schemas/EnumDescriptionsSchemaFilter.cs @@ -62,8 +62,7 @@ public void Apply(OpenApiSchema schema, SchemaFilterContext context) var summaryNode = enumNode.SelectSingleNode("summary"); if (summaryNode != null) { - var xml = XmlCommentsTextHelper.Humanize(summaryNode.InnerXml); - return XmlCommentsHelper.ToMarkdown(xml); + return XmlCommentsTextHelper.Humanize(summaryNode.InnerXml); } return null; diff --git a/src/Tingle.AspNetCore.Swagger/Filters/Schemas/MarkdownSchemaFilter.cs b/src/Tingle.AspNetCore.Swagger/Filters/Schemas/MarkdownSchemaFilter.cs deleted file mode 100644 index 41c74f9..0000000 --- a/src/Tingle.AspNetCore.Swagger/Filters/Schemas/MarkdownSchemaFilter.cs +++ /dev/null @@ -1,43 +0,0 @@ -using Microsoft.OpenApi.Any; -using Microsoft.OpenApi.Models; -using Swashbuckle.AspNetCore.SwaggerGen; - -namespace Tingle.AspNetCore.Swagger.Filters.Schemas; - -/// -/// An that converts XML comments to Markdown. -/// -public class MarkdownSchemaFilter : ISchemaFilter -{ - /// - public void Apply(OpenApiSchema schema, SchemaFilterContext context) - { - schema.Description = XmlCommentsHelper.ToMarkdown(schema.Description); - - // The InheritDocSchemaFilter modifies all the properties so we need to do the same here - - // Handle parameters such as in form data - if (context.ParameterInfo != null && context.MemberInfo != null) - { - ApplyPropertyComments(schema); - } - - if (schema.Properties == null) return; - - // Add the summary and examples for the properties. - foreach (var entry in schema.Properties) - { - ApplyPropertyComments(entry.Value); - } - } - - private static void ApplyPropertyComments(OpenApiSchema propertySchema) - { - propertySchema.Description = XmlCommentsHelper.ToMarkdown(propertySchema.Description); - - if (propertySchema.Example is OpenApiString str) - { - propertySchema.Example = new OpenApiString(XmlCommentsHelper.ToMarkdown(str.Value)); - } - } -} diff --git a/src/Tingle.AspNetCore.Swagger/XmlCommentsHelper.cs b/src/Tingle.AspNetCore.Swagger/XmlCommentsHelper.cs deleted file mode 100644 index e8ec6be..0000000 --- a/src/Tingle.AspNetCore.Swagger/XmlCommentsHelper.cs +++ /dev/null @@ -1,31 +0,0 @@ -using System.Diagnostics.CodeAnalysis; -using System.Text.RegularExpressions; - -namespace Tingle.AspNetCore.Swagger; - -/// -/// Functionality for working with XML comments in Swagger. -/// -public static partial class XmlCommentsHelper -{ - // TODO: Contribute this back to the library - - private static readonly Regex BrPattern = GetBrPattern(); - - /// - [return: NotNullIfNotNull(nameof(text))] - public static string? ToMarkdown(string? text) - { - if (text is null) return null; - - return text.ConvertBrTags(); - } - - private static string ConvertBrTags(this string text) - { - return BrPattern.Replace(text, m => Environment.NewLine); - } - - [GeneratedRegex(@"(
||
)")] - private static partial Regex GetBrPattern(); -} diff --git a/tests/Tingle.AspNetCore.Swagger.Tests/FilterCreationTests.cs b/tests/Tingle.AspNetCore.Swagger.Tests/FilterCreationTests.cs index e27152e..09921cf 100644 --- a/tests/Tingle.AspNetCore.Swagger.Tests/FilterCreationTests.cs +++ b/tests/Tingle.AspNetCore.Swagger.Tests/FilterCreationTests.cs @@ -2,10 +2,6 @@ using Microsoft.Extensions.FileProviders; using Microsoft.Extensions.Options; using Swashbuckle.AspNetCore.SwaggerGen; -using Tingle.AspNetCore.Swagger.Filters.Documents; -using Tingle.AspNetCore.Swagger.Filters.Operations; -using Tingle.AspNetCore.Swagger.Filters.Parameters; -using Tingle.AspNetCore.Swagger.Filters.RequestBodies; using Tingle.AspNetCore.Swagger.Filters.Schemas; namespace Tingle.AspNetCore.Swagger.Tests; @@ -39,50 +35,12 @@ public void InheritDocSchemaFilter_CanBe_Created() Assert.Single(options.SchemaFilters.OfType()); } - [Fact] - public void MarkdownFilters_AreAdded() - { - var env = new FakeWebHostEnvironment { ApplicationName = "Test", ContentRootPath = Environment.CurrentDirectory, }; - var services = new ServiceCollection().AddLogging() - .AddSwaggerGen(o => o.IncludeXmlComments(env, includeControllerXmlComments: true)) - .AddSwaggerXmlToMarkdown() - .BuildServiceProvider(); - - var options = services.GetRequiredService>().Value; - - Assert.Single(options.DocumentFilterDescriptors.Where(d => d.Type == typeof(MarkdownDocumentFilter))); - Assert.Single(options.OperationFilterDescriptors.Where(d => d.Type == typeof(MarkdownOperationFilter))); - Assert.Single(options.ParameterFilterDescriptors.Where(d => d.Type == typeof(MarkdownParameterFilter))); - Assert.Single(options.RequestBodyFilterDescriptors.Where(d => d.Type == typeof(MarkdownRequestBodyFilter))); - Assert.Single(options.SchemaFilterDescriptors.Where(d => d.Type == typeof(MarkdownSchemaFilter))); - } - - [Fact] - public void MarkdownFilters_CanBe_Created() - { - var env = new FakeWebHostEnvironment { ApplicationName = "Test", ContentRootPath = Environment.CurrentDirectory, }; - var services = new ServiceCollection().AddLogging() - .AddSwaggerGen(o => o.IncludeXmlComments(env, includeControllerXmlComments: true)) - .AddSwaggerXmlToMarkdown() - .AddSingleton(env) - .BuildServiceProvider(); - - var optionsSchema = services.GetRequiredService>().Value; - Assert.Single(optionsSchema.SchemaFilters.OfType()); - - var options = services.GetRequiredService>().Value; - Assert.Single(options.DocumentFilters.OfType()); - Assert.Single(options.OperationFilters.OfType()); - Assert.Single(options.ParameterFilters.OfType()); - Assert.Single(options.RequestBodyFilters.OfType()); - } - [Fact] public void EnumDescriptionsFilters_AreAdded() { var env = new FakeWebHostEnvironment { ApplicationName = "Test", ContentRootPath = Environment.CurrentDirectory, }; var services = new ServiceCollection().AddLogging() - .AddSwaggerGen(o => o.IncludeXmlComments(env, includeControllerXmlComments: true)) + .AddSwaggerGen(o => o.IncludeXmlComments(env, includeControllerXmlComments: true)) .AddSwaggerEnumDescriptions() .BuildServiceProvider(); @@ -96,7 +54,7 @@ public void EnumDescriptionsFilter_CanBe_Created() { var env = new FakeWebHostEnvironment { ApplicationName = "Test", ContentRootPath = Environment.CurrentDirectory, }; var services = new ServiceCollection().AddLogging() - .AddSwaggerGen(o => o.IncludeXmlComments(env, includeControllerXmlComments: true)) + .AddSwaggerGen(o => o.IncludeXmlComments(env, includeControllerXmlComments: true)) .AddSwaggerEnumDescriptions() .BuildServiceProvider(); diff --git a/tests/Tingle.AspNetCore.Swagger.Tests/XmlCommentsHelperTests.cs b/tests/Tingle.AspNetCore.Swagger.Tests/XmlCommentsHelperTests.cs deleted file mode 100644 index 3302f29..0000000 --- a/tests/Tingle.AspNetCore.Swagger.Tests/XmlCommentsHelperTests.cs +++ /dev/null @@ -1,14 +0,0 @@ -namespace Tingle.AspNetCore.Swagger.Tests; - -public class XmlCommentsHelperTests -{ - [Theory] - [InlineData("
", "\r\n")] - [InlineData("
", "\r\n")] - [InlineData("
", "\r\n")] - public void ToMarkdown_Converts_Br(string input, string expected) - { - var actual = XmlCommentsHelper.ToMarkdown(input); - Assert.Equal(expected, actual, false, true); - } -}