Add XML docs descriptions

Add OpenAPI descriptions for schemas from XML documentation.

Author: martincostello

src/API/API.csproj

@@ -10,7 +10,7 @@
     <InvariantGlobalization>true</InvariantGlobalization>
     <OutputType>Exe</OutputType>
     <PreserveCompilationContext>true</PreserveCompilationContext>
-    <PublishAot>true</PublishAot>
+    <PublishAot>false</PublishAot>
     <PublishSelfContained>true</PublishSelfContained>
     <RootNamespace>MartinCostello.Api</RootNamespace>
     <TargetFramework>net9.0</TargetFramework>

src/API/Extensions/IServiceCollectionExtensions.cs

@@ -39,6 +39,7 @@ public static IServiceCollection AddOpenApiDocumentation(this IServiceCollection
             options.AddOperationTransformer<AddResponseDescriptionTransformer>();
             options.AddOperationTransformer<RemoveStyleCopPrefixesTransformer>();
             options.AddSchemaTransformer<AddExamplesTransformer>();
+            options.AddSchemaTransformer<AddSchemaDescriptionsTransformer>();
             options.AddSchemaTransformer<RemoveStyleCopPrefixesTransformer>();
         });
 

src/API/OpenApi/AddSchemaDescriptionsTransformer.cs

@@ -0,0 +1,61 @@
+// Copyright (c) Martin Costello, 2016. All rights reserved.
+// Licensed under the MIT license. See the LICENSE file in the project root for full license information.
+
+using System.Xml;
+using System.Xml.XPath;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi.Models;
+
+namespace MartinCostello.Api.OpenApi;
+
+/// <summary>
+/// A class that adds descriptions to the schemas of OpenAPI documents. This class cannot be inherited.
+/// </summary>
+public sealed class AddSchemaDescriptionsTransformer : IOpenApiSchemaTransformer
+{
+    /// <inheritdoc/>
+    public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)
+    {
+        if (schema.Description != null)
+        {
+            return Task.CompletedTask;
+        }
+
+        var thisAssembly = GetType().Assembly;
+
+        if (context.JsonTypeInfo.Type.Assembly == thisAssembly)
+        {
+            var navigator = CreateNavigator();
+            var description = navigator.SelectSingleNode($"/doc/members/member[@name='T:{context.JsonTypeInfo.Type.FullName}']/summary");
+
+            if (!string.IsNullOrEmpty(description?.InnerXml))
+            {
+                schema.Description = description.Value.Trim();
+            }
+        }
+        else if (context.JsonPropertyInfo?.DeclaringType.Assembly == thisAssembly)
+        {
+            var navigator = CreateNavigator();
+
+            var typeName = context.JsonPropertyInfo.DeclaringType.FullName;
+            var propertyName = $"{char.ToUpperInvariant(context.JsonPropertyInfo.Name[0])}{context.JsonPropertyInfo.Name[1..]}";
+
+            var description = navigator.SelectSingleNode(
+                $"/doc/members/member[@name='P:{typeName}{Type.Delimiter}{propertyName}']/summary");
+
+            if (!string.IsNullOrEmpty(description?.InnerXml))
+            {
+                schema.Description = description.Value.Trim();
+            }
+        }
+
+        return Task.CompletedTask;
+    }
+
+    private static XPathNavigator CreateNavigator()
+    {
+        var path = Path.Combine(AppContext.BaseDirectory, "API.xml");
+        using var reader = XmlReader.Create(path);
+        return new XPathDocument(reader).CreateNavigator();
+    }
+}