Support <example> tags. Fixes #1170

Author: commonsensesoftware

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

@@ -16,6 +16,7 @@
  </ItemGroup>
 
  <ItemGroup>
+  <PackageReference Include="Microsoft.OpenApi" Version="2.0.0" />
   <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.*" />
  </ItemGroup>
 

src/AspNetCore/WebApi/src/Asp.Versioning.OpenApi/Transformers/XmlComments.cs

@@ -42,40 +42,48 @@ public class XmlComments
     /// Gets the <c>summary</c> from the specified member, if any.
     /// </summary>
     /// <param name="member">The member to get the summary from.</param>
-    /// <returns>The corresponding summary or an empty string.</returns>
+    /// <returns>The corresponding <c>&lt;summary&gt;</c> or an empty string.</returns>
     public string GetSummary( MemberInfo member )
         => GetMember( member )?.Element( "summary" )?.Value.Trim() ?? string.Empty;
 
     /// <summary>
     /// Gets the <c>description</c> from the specified member, if any.
     /// </summary>
     /// <param name="member">The member to get the description from.</param>
-    /// <returns>The corresponding description or an empty string.</returns>
+    /// <returns>The corresponding <c>&lt;description&gt;</c> or an empty string.</returns>
     public string GetDescription( MemberInfo member )
         => GetMember( member )?.Element( "description" )?.Value.Trim() ?? string.Empty;
 
     /// <summary>
     /// Gets the <c>remarks</c> from the specified member, if any.
     /// </summary>
     /// <param name="member">The member to get the remarks from.</param>
-    /// <returns>The corresponding remarks or an empty string.</returns>
+    /// <returns>The corresponding <c>&lt;remarks&gt;</c> or an empty string.</returns>
     public string GetRemarks( MemberInfo member )
         => GetMember( member )?.Element( "remarks" )?.Value.Trim() ?? string.Empty;
 
     /// <summary>
     /// Gets the <c>returns</c> from the specified member, if any.
     /// </summary>
     /// <param name="member">The member to get the returns from.</param>
-    /// <returns>The corresponding returns or an empty string.</returns>
+    /// <returns>The corresponding <c>&lt;returns&gt;</c> or an empty string.</returns>
     public string GetReturns( MemberInfo member )
         => GetMember( member )?.Element( "returns" )?.Value.Trim() ?? string.Empty;
 
+    /// <summary>
+    /// Gets the <c>example</c> from the specified member, if any.
+    /// </summary>
+    /// <param name="member">The member to get the example from.</param>
+    /// <returns>The corresponding <c>&lt;example&gt;</c> or an empty string.</returns>
+    public string GetExample( MemberInfo member )
+        => GetMember( member )?.Element( "example" )?.Value.Trim() ?? string.Empty;
+
     /// <summary>
     /// Gets the <c>param</c> description from the specified member, if any.
     /// </summary>
     /// <param name="member">The member to get the parameter from.</param>
     /// <param name="name">The name of the parameter.</param>
-    /// <returns>The corresponding returns or an empty string.</returns>
+    /// <returns>The corresponding description or an empty string.</returns>
     public string GetParameterDescription( MemberInfo member, string name )
     {
         if ( GetMember( member ) is { } element )
@@ -89,6 +97,50 @@ public string GetParameterDescription( MemberInfo member, string name )
         return string.Empty;
     }
 
+    /// <summary>
+    /// Gets the parameter <c>example</c> from the specified member, if any.
+    /// </summary>
+    /// <param name="member">The member to get the parameter from.</param>
+    /// <param name="name">The name of the parameter.</param>
+    /// <returns>The corresponding <c>&lt;example&gt;</c> or an empty string.</returns>
+    public string GetParameterExample( MemberInfo member, string name )
+    {
+        if ( GetMember( member ) is { } element )
+        {
+            return element.Elements( "param" )
+                          .FirstOrDefault( x => x.Attribute( "name" )?.Value == name )?
+                          .Attribute( "example" )?
+                          .Value
+                          .Trim() ?? string.Empty;
+        }
+
+        return string.Empty;
+    }
+
+    /// <summary>
+    /// Gets the <c>deprecated</c> attribute from the specified member, if any.
+    /// </summary>
+    /// <param name="member">The member to get the parameter from.</param>
+    /// <param name="name">The name of the parameter.</param>
+    /// <returns><c>true</c> if the <c>deprecated</c> attribute is present with a value of <c>"true"</c>;
+    /// otherwise <c>false</c>.</returns>
+    public bool IsParameterDeprecated( MemberInfo member, string name )
+    {
+        if ( GetMember( member ) is { } element )
+        {
+            var deprecated = element.Elements( "param" )
+                                    .FirstOrDefault( x => x.Attribute( "name" )?.Value == name )?
+                                    .Attribute( "deprecated" )?.Value;
+
+            if ( deprecated is { } value )
+            {
+                return StringComparer.OrdinalIgnoreCase.Equals( value, bool.TrueString );
+            }
+        }
+
+        return false;
+    }
+
     /// <summary>
     /// Gets the <c>response</c> description from the specified member, if any.
     /// </summary>

src/AspNetCore/WebApi/src/Asp.Versioning.OpenApi/Transformers/XmlCommentsTransformer.cs

@@ -8,6 +8,8 @@ namespace Asp.Versioning.OpenApi.Transformers;
 using Microsoft.OpenApi;
 using System;
 using System.Reflection;
+using System.Text.Json;
+using System.Text.Json.Nodes;
 using System.Threading;
 using static System.Reflection.BindingFlags;
 
@@ -45,24 +47,46 @@ public virtual Task TransformAsync(
         ArgumentNullException.ThrowIfNull( schema );
         ArgumentNullException.ThrowIfNull( context );
 
-        if ( schema.Properties is not { } properties
-            || context.JsonTypeInfo?.Type is not Type type )
+        if ( context.JsonTypeInfo?.Type is not Type type )
         {
             return Task.CompletedTask;
         }
 
-        if ( string.IsNullOrEmpty( schema.Description ) )
+        var description = schema.Description;
+
+        if ( string.IsNullOrEmpty( description )
+             && !string.IsNullOrEmpty( description = Documentation.GetSummary( type ) ) )
         {
-            schema.Description = Documentation.GetSummary( type );
+            schema.Description = description;
+        }
+
+        if ( schema.Example is null && ToJson( Documentation.GetExample( type ) ) is { } example )
+        {
+            schema.Example = example;
+        }
+
+        if ( schema.Properties is not { } properties )
+        {
+            return Task.CompletedTask;
         }
 
         foreach ( var (name, prop) in properties )
         {
             if ( prop is not null
-                && string.IsNullOrEmpty( prop.Description )
-                && type.GetProperty( name, IgnoreCase | Instance | Public ) is { } property )
+                 && type.GetProperty( name, IgnoreCase | Instance | Public ) is { } property )
             {
-                prop.Description = Documentation.GetSummary( property );
+                if ( string.IsNullOrEmpty( prop.Description )
+                     && !string.IsNullOrEmpty( description = Documentation.GetSummary( property ) ) )
+                {
+                    prop.Description = description;
+                }
+
+                if ( prop.Example is null
+                     && prop.Examples is not null
+                     && ( example = ToJson( Documentation.GetExample( property ) ) ) is not null )
+                {
+                    prop.Examples.Add( example );
+                }
             }
         }
 
@@ -88,16 +112,19 @@ public virtual Task TransformAsync(
             operation.Summary = Documentation.GetSummary( method );
         }
 
-        if ( string.IsNullOrEmpty( operation.Description ) )
+        var description = operation.Description;
+
+        if ( string.IsNullOrEmpty( description )
+             && !string.IsNullOrEmpty( description = Documentation.GetDescription( method ) ) )
         {
-            operation.Description = Documentation.GetDescription( method );
+            operation.Description = description;
         }
 
         if ( operation.Responses is { } responses )
         {
             foreach ( var (statusCode, response) in responses )
             {
-                var description = Documentation.GetResponseDescription( method, statusCode );
+                description = Documentation.GetResponseDescription( method, statusCode );
 
                 if ( !string.IsNullOrEmpty( description ) )
                 {
@@ -118,18 +145,40 @@ public virtual Task TransformAsync(
         {
             var parameter = parameters[i];
 
-            if ( !string.IsNullOrEmpty( parameter.Name ) && string.IsNullOrEmpty( parameter.Description ) )
+            if ( string.IsNullOrEmpty( parameter.Name ) )
             {
-                for ( var j = 0; j < args.Count; j++ )
+                continue;
+            }
+
+            for ( var j = 0; j < args.Count; j++ )
+            {
+                var arg = args[j];
+
+                if ( arg.Name != parameter.Name )
                 {
-                    var arg = args[i];
+                    continue;
+                }
+
+                var name = arg.ParameterDescriptor.Name;
+
+                if ( string.IsNullOrEmpty( parameter.Description )
+                     && !string.IsNullOrEmpty( description = Documentation.GetParameterDescription( method, name ) ) )
+                {
+                    parameter.Description = description;
+                }
 
-                    if ( arg.Name == parameter.Name )
+                if ( parameter is OpenApiParameter param )
+                {
+                    if ( param.Example is null
+                         && ToJson( Documentation.GetParameterExample( method, name ) ) is { } example )
                     {
-                        var name = arg.ParameterDescriptor.Name;
-                        parameter.Description = Documentation.GetParameterDescription( method, name );
+                        param.Example = example;
                     }
+
+                    param.Deprecated |= Documentation.IsParameterDeprecated( method, name );
                 }
+
+                break;
             }
         }
 
@@ -159,4 +208,21 @@ private static bool TryResolveMethod( ActionDescriptor action, [MaybeNullWhen( f
         method = default;
         return false;
     }
+
+    private static JsonNode? ToJson( string? example )
+    {
+        if ( string.IsNullOrEmpty( example ) )
+        {
+            return default;
+        }
+
+        try
+        {
+            return JsonNode.Parse( example );
+        }
+        catch ( JsonException )
+        {
+            return JsonNode.Parse( $"\"{example}\"" );
+        }
+    }
 }

src/AspNetCore/WebApi/test/Asp.Versioning.OpenApi.Tests/Content/v1-minimal.json

@@ -28,7 +28,8 @@
               "pattern": "^-?(?:0|[1-9]\\d*)$",
               "type": "integer",
               "format": "int32"
-            }
+            },
+            "example": 42
           },
           {
             "name": "api-version",

src/AspNetCore/WebApi/test/Asp.Versioning.OpenApi.Tests/Content/v1-mixed.json

@@ -28,7 +28,8 @@
               "pattern": "^-?(?:0|[1-9]\\d*)$",
               "type": "integer",
               "format": "int32"
-            }
+            },
+            "example": 42
           },
           {
             "name": "api-version",
@@ -82,7 +83,8 @@
                 "string"
               ],
               "format": "int32"
-            }
+            },
+            "example": 42
           },
           {
             "name": "api-version",

src/AspNetCore/WebApi/test/Asp.Versioning.OpenApi.Tests/Content/v1.json

@@ -30,7 +30,8 @@
                 "string"
               ],
               "format": "int32"
-            }
+            },
+            "example": 42
           },
           {
             "name": "api-version",

src/AspNetCore/WebApi/test/Asp.Versioning.OpenApi.Tests/Simulators/MinimalApi.cs

@@ -10,7 +10,7 @@ public static class MinimalApi
     /// Test
     /// </summary>
     /// <description>A test API.</description>
-    /// <param name="id">A test parameter.</param>
+    /// <param name="id" example="42">A test parameter.</param>
     /// <returns>The original identifier.</returns>
     /// <response code="200">Pass</response>
     /// <response code="400">Fail</response>

src/AspNetCore/WebApi/test/Asp.Versioning.OpenApi.Tests/Simulators/Model.cs

@@ -0,0 +1,22 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+#pragma warning disable SA1629
+
+namespace Asp.Versioning.OpenApi.Simulators;
+
+/// <summary>
+/// Represents a model.
+/// </summary>
+public class Model
+{
+    /// <summary>
+    /// Gets or sets the user associated with the model.
+    /// </summary>
+    /// <example>
+    /// {
+    ///     "userName": "John Doe",
+    ///     "email": "john.doe@example.com"
+    /// }
+    /// </example>
+    public User User { get; set; }
+}

src/AspNetCore/WebApi/test/Asp.Versioning.OpenApi.Tests/Simulators/TestController.cs

@@ -16,7 +16,7 @@ public class TestController : ControllerBase
     /// Test
     /// </summary>
     /// <description>A test API.</description>
-    /// <param name="id">A test parameter.</param>
+    /// <param name="id" example="42">A test parameter.</param>
     /// <returns>The original identifier.</returns>
     /// <response code="200">Pass</response>
     /// <response code="400">Fail</response>

src/AspNetCore/WebApi/test/Asp.Versioning.OpenApi.Tests/Simulators/User.cs

@@ -0,0 +1,23 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+#pragma warning disable SA1629
+
+namespace Asp.Versioning.OpenApi.Simulators;
+
+/// <summary>
+/// Represents a user.
+/// </summary>
+public class User
+{
+    /// <summary>
+    /// Gets or sets the username associated with the account.
+    /// </summary>
+    /// <example>John Doe</example>
+    public string UserName { get; set; }
+
+    /// <summary>
+    /// Gets or sets the email address associated with the user.
+    /// </summary>
+    /// <example>user@example.com</example>
+    public string Email { get; set; }
+}