From 15e467517ddbacb7d2ba496516edd054b082c5a4 Mon Sep 17 00:00:00 2001 From: Nico Lachmuth Date: Thu, 5 Mar 2026 14:24:38 +0100 Subject: [PATCH] documentation support for abp api description --- .../ApiExploring/IXmlDocumentationProvider.cs | 21 ++ .../ApiExploring/XmlDocumentationProvider.cs | 175 +++++++++++++++ .../AspNetCoreApiDescriptionModelProvider.cs | 114 ++++++++-- .../Modeling/ActionApiDescriptionModel.cs | 8 + ...pplicationApiDescriptionModelRequestDto.cs | 2 + .../Modeling/ControllerApiDescriptionModel.cs | 12 + .../MethodParameterApiDescriptionModel.cs | 6 + .../Modeling/ParameterApiDescriptionModel.cs | 6 + .../Modeling/PropertyApiDescriptionModel.cs | 6 + .../ReturnValueApiDescriptionModel.cs | 2 + .../Http/Modeling/TypeApiDescriptionModel.cs | 8 + ...iDefinitionController_Description_Tests.cs | 205 ++++++++++++++++++ .../Volo.Abp.TestApp/Volo.Abp.TestApp.csproj | 1 + .../Application/DocumentedAppService.cs | 40 ++++ .../TestApp/Application/Dto/DocumentedDto.cs | 25 +++ .../Application/IDocumentedAppService.cs | 28 +++ 16 files changed, 645 insertions(+), 14 deletions(-) create mode 100644 framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ApiExploring/IXmlDocumentationProvider.cs create mode 100644 framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ApiExploring/XmlDocumentationProvider.cs create mode 100644 framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/ApiExploring/AbpApiDefinitionController_Description_Tests.cs create mode 100644 framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/DocumentedAppService.cs create mode 100644 framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/Dto/DocumentedDto.cs create mode 100644 framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/IDocumentedAppService.cs diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ApiExploring/IXmlDocumentationProvider.cs b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ApiExploring/IXmlDocumentationProvider.cs new file mode 100644 index 0000000000..f305f74c6e --- /dev/null +++ b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ApiExploring/IXmlDocumentationProvider.cs @@ -0,0 +1,21 @@ +using System; +using System.Reflection; + +namespace Volo.Abp.AspNetCore.Mvc.ApiExploring; + +public interface IXmlDocumentationProvider +{ + string? GetSummary(Type type); + + string? GetRemarks(Type type); + + string? GetSummary(MethodInfo method); + + string? GetRemarks(MethodInfo method); + + string? GetReturns(MethodInfo method); + + string? GetParameterSummary(MethodInfo method, string parameterName); + + string? GetSummary(PropertyInfo property); +} diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ApiExploring/XmlDocumentationProvider.cs b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ApiExploring/XmlDocumentationProvider.cs new file mode 100644 index 0000000000..40cb546cc5 --- /dev/null +++ b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ApiExploring/XmlDocumentationProvider.cs @@ -0,0 +1,175 @@ +using System; +using System.Collections.Concurrent; +using System.IO; +using System.Linq; +using System.Reflection; +using System.Text.RegularExpressions; +using System.Xml.Linq; +using System.Xml.XPath; +using Volo.Abp.DependencyInjection; + +namespace Volo.Abp.AspNetCore.Mvc.ApiExploring; + +public class XmlDocumentationProvider : IXmlDocumentationProvider, ISingletonDependency +{ + private readonly ConcurrentDictionary _xmlDocCache = new(); + + public string? GetSummary(Type type) + { + var memberName = GetMemberNameForType(type); + return GetDocumentationElement(type.Assembly, memberName, "summary"); + } + + public string? GetRemarks(Type type) + { + var memberName = GetMemberNameForType(type); + return GetDocumentationElement(type.Assembly, memberName, "remarks"); + } + + public string? GetSummary(MethodInfo method) + { + var memberName = GetMemberNameForMethod(method); + return GetDocumentationElement(method.DeclaringType!.Assembly, memberName, "summary"); + } + + public string? GetRemarks(MethodInfo method) + { + var memberName = GetMemberNameForMethod(method); + return GetDocumentationElement(method.DeclaringType!.Assembly, memberName, "remarks"); + } + + public string? GetReturns(MethodInfo method) + { + var memberName = GetMemberNameForMethod(method); + return GetDocumentationElement(method.DeclaringType!.Assembly, memberName, "returns"); + } + + public string? GetParameterSummary(MethodInfo method, string parameterName) + { + var memberName = GetMemberNameForMethod(method); + var doc = LoadXmlDocumentation(method.DeclaringType!.Assembly); + if (doc == null) + { + return null; + } + + var memberNode = doc.XPathSelectElement($"//member[@name='{memberName}']"); + var paramNode = memberNode?.XPathSelectElement($"param[@name='{parameterName}']"); + return CleanXmlText(paramNode); + } + + public string? GetSummary(PropertyInfo property) + { + var memberName = GetMemberNameForProperty(property); + return GetDocumentationElement(property.DeclaringType!.Assembly, memberName, "summary"); + } + + private string? GetDocumentationElement(Assembly assembly, string memberName, string elementName) + { + var doc = LoadXmlDocumentation(assembly); + if (doc == null) + { + return null; + } + + var memberNode = doc.XPathSelectElement($"//member[@name='{memberName}']"); + var element = memberNode?.Element(elementName); + return CleanXmlText(element); + } + + private XDocument? LoadXmlDocumentation(Assembly assembly) + { + return _xmlDocCache.GetOrAdd(assembly, static asm => + { + if (string.IsNullOrEmpty(asm.Location)) + { + return null; + } + + var xmlFilePath = Path.ChangeExtension(asm.Location, ".xml"); + if (!File.Exists(xmlFilePath)) + { + return null; + } + + try + { + return XDocument.Load(xmlFilePath); + } + catch + { + return null; + } + }); + } + + private static string? CleanXmlText(XElement? element) + { + if (element == null) + { + return null; + } + + var text = element.Value; + if (string.IsNullOrWhiteSpace(text)) + { + return null; + } + + return Regex.Replace(text.Trim(), @"\s+", " "); + } + + private static string GetMemberNameForType(Type type) + { + return $"T:{GetTypeFullName(type)}"; + } + + private static string GetMemberNameForMethod(MethodInfo method) + { + var typeName = GetTypeFullName(method.DeclaringType!); + var parameters = method.GetParameters(); + if (parameters.Length == 0) + { + return $"M:{typeName}.{method.Name}"; + } + + var paramTypes = string.Join(",", + parameters.Select(p => GetParameterTypeName(p.ParameterType))); + return $"M:{typeName}.{method.Name}({paramTypes})"; + } + + private static string GetMemberNameForProperty(PropertyInfo property) + { + var typeName = GetTypeFullName(property.DeclaringType!); + return $"P:{typeName}.{property.Name}"; + } + + private static string GetTypeFullName(Type type) + { + return type.FullName?.Replace('+', '.') ?? type.Name; + } + + private static string GetParameterTypeName(Type type) + { + if (type.IsGenericType) + { + var genericDef = type.GetGenericTypeDefinition(); + var defName = genericDef.FullName!; + defName = defName[..defName.IndexOf('`')]; + var args = string.Join(",", type.GetGenericArguments().Select(GetParameterTypeName)); + return $"{defName}{{{args}}}"; + } + + if (type.IsArray) + { + return GetParameterTypeName(type.GetElementType()!) + "[]"; + } + + if (type.IsByRef) + { + return GetParameterTypeName(type.GetElementType()!) + "@"; + } + + return type.FullName ?? type.Name; + } +} diff --git a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AspNetCoreApiDescriptionModelProvider.cs b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AspNetCoreApiDescriptionModelProvider.cs index 2df5dea048..4dfb7b5e08 100644 --- a/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AspNetCoreApiDescriptionModelProvider.cs +++ b/framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AspNetCoreApiDescriptionModelProvider.cs @@ -1,5 +1,7 @@ using System; using System.Collections.Generic; +using System.ComponentModel; +using System.ComponentModel.DataAnnotations; using System.Linq; using System.Reflection; using Asp.Versioning; @@ -12,6 +14,7 @@ using Microsoft.AspNetCore.Mvc.ModelBinding; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; using Microsoft.Extensions.Options; +using Volo.Abp.AspNetCore.Mvc.ApiExploring; using Volo.Abp.AspNetCore.Mvc.Conventions; using Volo.Abp.AspNetCore.Mvc.Utils; using Volo.Abp.DependencyInjection; @@ -29,17 +32,20 @@ public class AspNetCoreApiDescriptionModelProvider : IApiDescriptionModelProvide private readonly IApiDescriptionGroupCollectionProvider _descriptionProvider; private readonly AbpAspNetCoreMvcOptions _abpAspNetCoreMvcOptions; private readonly AbpApiDescriptionModelOptions _modelOptions; + private readonly IXmlDocumentationProvider _xmlDocProvider; public AspNetCoreApiDescriptionModelProvider( IOptions options, IApiDescriptionGroupCollectionProvider descriptionProvider, IOptions abpAspNetCoreMvcOptions, - IOptions modelOptions) + IOptions modelOptions, + IXmlDocumentationProvider xmlDocProvider) { _options = options.Value; _descriptionProvider = descriptionProvider; _abpAspNetCoreMvcOptions = abpAspNetCoreMvcOptions.Value; _modelOptions = modelOptions.Value; + _xmlDocProvider = xmlDocProvider; Logger = NullLogger.Instance; } @@ -161,10 +167,21 @@ public class AspNetCoreApiDescriptionModelProvider : IApiDescriptionModelProvide if (input.IncludeTypes) { - AddCustomTypesToModel(applicationModel, method); + AddCustomTypesToModel(applicationModel, method, input.IncludeDescriptions); } AddParameterDescriptionsToModel(actionModel, method, apiDescription); + + if (input.IncludeDescriptions) + { + if (controllerModel.Summary == null && controllerModel.Description == null && controllerModel.DisplayName == null) + { + PopulateControllerDescriptions(controllerModel, controllerType); + } + + PopulateActionDescriptions(actionModel, method); + PopulateParameterDescriptions(actionModel, method); + } } private static List GetSupportedVersions(Type controllerType, MethodInfo method, @@ -191,18 +208,18 @@ public class AspNetCoreApiDescriptionModelProvider : IApiDescriptionModelProvide return supportedVersions.Select(v => v.ToString()).Distinct().ToList(); } - private void AddCustomTypesToModel(ApplicationApiDescriptionModel applicationModel, MethodInfo method) + private void AddCustomTypesToModel(ApplicationApiDescriptionModel applicationModel, MethodInfo method, bool includeDescriptions) { foreach (var parameterInfo in method.GetParameters()) { - AddCustomTypesToModel(applicationModel, parameterInfo.ParameterType); + AddCustomTypesToModel(applicationModel, parameterInfo.ParameterType, includeDescriptions); } - AddCustomTypesToModel(applicationModel, method.ReturnType); + AddCustomTypesToModel(applicationModel, method.ReturnType, includeDescriptions); } - private static void AddCustomTypesToModel(ApplicationApiDescriptionModel applicationModel, - Type? type) + private void AddCustomTypesToModel(ApplicationApiDescriptionModel applicationModel, + Type? type, bool includeDescriptions) { if (type == null) { @@ -229,14 +246,14 @@ public class AspNetCoreApiDescriptionModelProvider : IApiDescriptionModelProvide if (TypeHelper.IsDictionary(type, out var keyType, out var valueType)) { - AddCustomTypesToModel(applicationModel, keyType); - AddCustomTypesToModel(applicationModel, valueType); + AddCustomTypesToModel(applicationModel, keyType, includeDescriptions); + AddCustomTypesToModel(applicationModel, valueType, includeDescriptions); return; } if (TypeHelper.IsEnumerable(type, out var itemType)) { - AddCustomTypesToModel(applicationModel, itemType); + AddCustomTypesToModel(applicationModel, itemType, includeDescriptions); return; } @@ -244,11 +261,11 @@ public class AspNetCoreApiDescriptionModelProvider : IApiDescriptionModelProvide { var genericTypeDefinition = type.GetGenericTypeDefinition(); - AddCustomTypesToModel(applicationModel, genericTypeDefinition); + AddCustomTypesToModel(applicationModel, genericTypeDefinition, includeDescriptions); foreach (var genericArgument in type.GetGenericArguments()) { - AddCustomTypesToModel(applicationModel, genericArgument); + AddCustomTypesToModel(applicationModel, genericArgument, includeDescriptions); } return; @@ -262,11 +279,16 @@ public class AspNetCoreApiDescriptionModelProvider : IApiDescriptionModelProvide applicationModel.Types[typeName] = TypeApiDescriptionModel.Create(type); - AddCustomTypesToModel(applicationModel, type.BaseType); + if (includeDescriptions) + { + PopulateTypeDescriptions(applicationModel.Types[typeName], type); + } + + AddCustomTypesToModel(applicationModel, type.BaseType, includeDescriptions); foreach (var propertyInfo in type.GetProperties().Where(p => p.DeclaringType == type)) { - AddCustomTypesToModel(applicationModel, propertyInfo.PropertyType); + AddCustomTypesToModel(applicationModel, propertyInfo.PropertyType, includeDescriptions); } } @@ -414,4 +436,68 @@ public class AspNetCoreApiDescriptionModelProvider : IApiDescriptionModelProvide return null; } + + private void PopulateControllerDescriptions(ControllerApiDescriptionModel controllerModel, Type controllerType) + { + controllerModel.Summary = _xmlDocProvider.GetSummary(controllerType); + controllerModel.Remarks = _xmlDocProvider.GetRemarks(controllerType); + controllerModel.Description = controllerType.GetCustomAttribute()?.Description; + controllerModel.DisplayName = controllerType.GetCustomAttribute()?.Name; + } + + private void PopulateActionDescriptions(ActionApiDescriptionModel actionModel, MethodInfo method) + { + actionModel.Summary = _xmlDocProvider.GetSummary(method); + actionModel.Remarks = _xmlDocProvider.GetRemarks(method); + actionModel.Description = method.GetCustomAttribute()?.Description; + actionModel.DisplayName = method.GetCustomAttribute()?.Name; + actionModel.ReturnValue.Summary = _xmlDocProvider.GetReturns(method); + } + + private void PopulateParameterDescriptions(ActionApiDescriptionModel actionModel, MethodInfo method) + { + foreach (var param in actionModel.ParametersOnMethod) + { + var paramInfo = method.GetParameters().FirstOrDefault(p => p.Name == param.Name); + if (paramInfo == null) + { + continue; + } + + param.Summary = _xmlDocProvider.GetParameterSummary(method, param.Name); + param.Description = paramInfo.GetCustomAttribute()?.Description; + param.DisplayName = paramInfo.GetCustomAttribute()?.Name; + } + + foreach (var param in actionModel.Parameters) + { + param.Summary = _xmlDocProvider.GetParameterSummary(method, param.NameOnMethod); + } + } + + private void PopulateTypeDescriptions(TypeApiDescriptionModel typeModel, Type type) + { + typeModel.Summary = _xmlDocProvider.GetSummary(type); + typeModel.Remarks = _xmlDocProvider.GetRemarks(type); + typeModel.Description = type.GetCustomAttribute()?.Description; + typeModel.DisplayName = type.GetCustomAttribute()?.Name; + + if (typeModel.Properties == null) + { + return; + } + + foreach (var propModel in typeModel.Properties) + { + var propInfo = type.GetProperty(propModel.Name, BindingFlags.Instance | BindingFlags.Public); + if (propInfo == null) + { + continue; + } + + propModel.Summary = _xmlDocProvider.GetSummary(propInfo); + propModel.Description = propInfo.GetCustomAttribute()?.Description; + propModel.DisplayName = propInfo.GetCustomAttribute()?.Name; + } + } } diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ActionApiDescriptionModel.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ActionApiDescriptionModel.cs index 83bacddd8c..7650e40f88 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ActionApiDescriptionModel.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ActionApiDescriptionModel.cs @@ -32,6 +32,14 @@ public class ActionApiDescriptionModel public string? ImplementFrom { get; set; } + public string? Summary { get; set; } + + public string? Remarks { get; set; } + + public string? Description { get; set; } + + public string? DisplayName { get; set; } + public ActionApiDescriptionModel() { diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ApplicationApiDescriptionModelRequestDto.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ApplicationApiDescriptionModelRequestDto.cs index 7f178c47e4..b70355daf5 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ApplicationApiDescriptionModelRequestDto.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ApplicationApiDescriptionModelRequestDto.cs @@ -3,4 +3,6 @@ public class ApplicationApiDescriptionModelRequestDto { public bool IncludeTypes { get; set; } + + public bool IncludeDescriptions { get; set; } } diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ControllerApiDescriptionModel.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ControllerApiDescriptionModel.cs index 40188c4b93..e27459d7e7 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ControllerApiDescriptionModel.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ControllerApiDescriptionModel.cs @@ -19,6 +19,14 @@ public class ControllerApiDescriptionModel public string Type { get; set; } = default!; + public string? Summary { get; set; } + + public string? Remarks { get; set; } + + public string? Description { get; set; } + + public string? DisplayName { get; set; } + public List Interfaces { get; set; } = default!; public Dictionary Actions { get; set; } = default!; @@ -66,6 +74,10 @@ public class ControllerApiDescriptionModel Type = Type, Interfaces = Interfaces, ControllerName = ControllerName, + Summary = Summary, + Remarks = Remarks, + Description = Description, + DisplayName = DisplayName, Actions = new Dictionary() }; diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/MethodParameterApiDescriptionModel.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/MethodParameterApiDescriptionModel.cs index c3ff20b897..fb5c47245c 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/MethodParameterApiDescriptionModel.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/MethodParameterApiDescriptionModel.cs @@ -19,6 +19,12 @@ public class MethodParameterApiDescriptionModel public object? DefaultValue { get; set; } + public string? Summary { get; set; } + + public string? Description { get; set; } + + public string? DisplayName { get; set; } + public MethodParameterApiDescriptionModel() { diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ParameterApiDescriptionModel.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ParameterApiDescriptionModel.cs index a863d1bfad..7bcac1510c 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ParameterApiDescriptionModel.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ParameterApiDescriptionModel.cs @@ -26,6 +26,12 @@ public class ParameterApiDescriptionModel public string? DescriptorName { get; set; } + public string? Summary { get; set; } + + public string? Description { get; set; } + + public string? DisplayName { get; set; } + public ParameterApiDescriptionModel() { diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/PropertyApiDescriptionModel.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/PropertyApiDescriptionModel.cs index ed604793b0..d0bf430546 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/PropertyApiDescriptionModel.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/PropertyApiDescriptionModel.cs @@ -32,6 +32,12 @@ public class PropertyApiDescriptionModel public bool IsNullable { get; set; } + public string? Summary { get; set; } + + public string? Description { get; set; } + + public string? DisplayName { get; set; } + public static PropertyApiDescriptionModel Create(PropertyInfo propertyInfo) { var customAttributes = propertyInfo.GetCustomAttributes(true); diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel.cs index e5a7e120a8..e77d2f7fea 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/ReturnValueApiDescriptionModel.cs @@ -11,6 +11,8 @@ public class ReturnValueApiDescriptionModel public string TypeSimple { get; set; } = default!; + public string? Summary { get; set; } + public ReturnValueApiDescriptionModel() { diff --git a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/TypeApiDescriptionModel.cs b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/TypeApiDescriptionModel.cs index d1733577e5..703c5a8583 100644 --- a/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/TypeApiDescriptionModel.cs +++ b/framework/src/Volo.Abp.Http/Volo/Abp/Http/Modeling/TypeApiDescriptionModel.cs @@ -20,6 +20,14 @@ public class TypeApiDescriptionModel public PropertyApiDescriptionModel[]? Properties { get; set; } + public string? Summary { get; set; } + + public string? Remarks { get; set; } + + public string? Description { get; set; } + + public string? DisplayName { get; set; } + public TypeApiDescriptionModel() { diff --git a/framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/ApiExploring/AbpApiDefinitionController_Description_Tests.cs b/framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/ApiExploring/AbpApiDefinitionController_Description_Tests.cs new file mode 100644 index 0000000000..e751e01cb1 --- /dev/null +++ b/framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/ApiExploring/AbpApiDefinitionController_Description_Tests.cs @@ -0,0 +1,205 @@ +using System.Linq; +using System.Threading.Tasks; +using Shouldly; +using Volo.Abp.Http.Modeling; +using Xunit; + +namespace Volo.Abp.AspNetCore.Mvc.ApiExploring; + +public class AbpApiDefinitionController_Description_Tests : AspNetCoreMvcTestBase +{ + [Fact] + public async Task Default_Should_Not_Include_Descriptions() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition"); + + var controller = GetDocumentedController(model); + controller.Summary.ShouldBeNull(); + controller.Remarks.ShouldBeNull(); + controller.Description.ShouldBeNull(); + controller.DisplayName.ShouldBeNull(); + } + + [Fact] + public async Task IncludeDescriptions_Should_Populate_Controller_Summary() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true"); + + var controller = GetDocumentedController(model); + controller.Summary.ShouldNotBeNullOrEmpty(); + controller.Summary.ShouldContain("documented application service"); + } + + [Fact] + public async Task IncludeDescriptions_Should_Populate_Controller_Remarks() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true"); + + var controller = GetDocumentedController(model); + controller.Remarks.ShouldNotBeNullOrEmpty(); + controller.Remarks.ShouldContain("integration tests"); + } + + [Fact] + public async Task IncludeDescriptions_Should_Populate_Controller_Description_Attribute() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true"); + + var controller = GetDocumentedController(model); + controller.Description.ShouldBe("Documented service description from attribute"); + } + + [Fact] + public async Task IncludeDescriptions_Should_Populate_Controller_DisplayName_Attribute() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true"); + + var controller = GetDocumentedController(model); + controller.DisplayName.ShouldBe("Documented Service"); + } + + [Fact] + public async Task IncludeDescriptions_Should_Populate_Action_Descriptions() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true"); + + var controller = GetDocumentedController(model); + var action = GetAction(controller, "GetGreeting"); + + action.Summary.ShouldNotBeNullOrEmpty(); + action.Summary.ShouldContain("greeting message"); + action.Remarks.ShouldBeNull(); + action.Description.ShouldBe("Get greeting description from attribute"); + action.DisplayName.ShouldBe("Get Greeting"); + } + + [Fact] + public async Task IncludeDescriptions_Should_Populate_ReturnValue_Summary() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true"); + + var controller = GetDocumentedController(model); + var action = GetAction(controller, "GetGreeting"); + + action.ReturnValue.Summary.ShouldNotBeNullOrEmpty(); + action.ReturnValue.Summary.ShouldContain("personalized greeting"); + } + + [Fact] + public async Task IncludeDescriptions_Should_Populate_ParameterOnMethod_Summary() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true"); + + var controller = GetDocumentedController(model); + var action = GetAction(controller, "GetGreeting"); + + var param = action.ParametersOnMethod.FirstOrDefault(p => p.Name == "name"); + param.ShouldNotBeNull(); + param.Summary.ShouldNotBeNullOrEmpty(); + param.Summary.ShouldContain("name of the person"); + } + + [Fact] + public async Task IncludeDescriptions_Should_Populate_Parameter_Summary() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true"); + + var controller = GetDocumentedController(model); + var action = GetAction(controller, "GetGreeting"); + + var param = action.Parameters.FirstOrDefault(p => p.NameOnMethod == "name"); + param.ShouldNotBeNull(); + param.Summary.ShouldNotBeNullOrEmpty(); + param.Summary.ShouldContain("name of the person"); + } + + [Fact] + public async Task IncludeDescriptions_With_IncludeTypes_Should_Populate_Type_Descriptions() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true&includeTypes=true"); + + model.Types.ShouldNotBeEmpty(); + + var documentedDtoType = model.Types.FirstOrDefault(t => t.Key.Contains("DocumentedDto")); + documentedDtoType.Value.ShouldNotBeNull(); + documentedDtoType.Value.Summary.ShouldNotBeNullOrEmpty(); + documentedDtoType.Value.Summary.ShouldContain("documented DTO"); + documentedDtoType.Value.Description.ShouldBe("Documented DTO description from attribute"); + documentedDtoType.Value.DisplayName.ShouldBe("Documented DTO"); + } + + [Fact] + public async Task IncludeDescriptions_With_IncludeTypes_Should_Populate_Property_Descriptions() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true&includeTypes=true"); + + var documentedDtoType = model.Types.FirstOrDefault(t => t.Key.Contains("DocumentedDto")); + documentedDtoType.Value.ShouldNotBeNull(); + documentedDtoType.Value.Properties.ShouldNotBeNull(); + + var nameProp = documentedDtoType.Value.Properties!.FirstOrDefault(p => p.Name == "Name"); + nameProp.ShouldNotBeNull(); + nameProp.Summary.ShouldNotBeNullOrEmpty(); + nameProp.Summary.ShouldContain("name of the documented item"); + nameProp.Description.ShouldBe("Name description from attribute"); + nameProp.DisplayName.ShouldBe("Item Name"); + + var valueProp = documentedDtoType.Value.Properties!.FirstOrDefault(p => p.Name == "Value"); + valueProp.ShouldNotBeNull(); + valueProp.Summary.ShouldNotBeNullOrEmpty(); + valueProp.Description.ShouldBe("Value description from attribute"); + valueProp.DisplayName.ShouldBeNull(); + } + + [Fact] + public async Task Default_Should_Not_Include_Type_Descriptions() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeTypes=true"); + + var documentedDtoType = model.Types.FirstOrDefault(t => t.Key.Contains("DocumentedDto")); + documentedDtoType.Value.ShouldNotBeNull(); + documentedDtoType.Value.Summary.ShouldBeNull(); + documentedDtoType.Value.Description.ShouldBeNull(); + } + + [Fact] + public async Task Action_Without_Descriptions_Should_Have_Null_Properties() + { + var model = await GetResponseAsObjectAsync( + "/api/abp/api-definition?includeDescriptions=true"); + + var peopleController = model.Modules.Values + .SelectMany(m => m.Controllers.Values) + .First(c => c.ControllerName == "People"); + + var action = peopleController.Actions.Values.First(a => a.Name == "GetPhones"); + action.Summary.ShouldBeNull(); + action.Description.ShouldBeNull(); + action.DisplayName.ShouldBeNull(); + } + + private static ControllerApiDescriptionModel GetDocumentedController(ApplicationApiDescriptionModel model) + { + return model.Modules.Values + .SelectMany(m => m.Controllers.Values) + .First(c => c.ControllerName == "Documented"); + } + + private static ActionApiDescriptionModel GetAction(ControllerApiDescriptionModel controller, string actionName) + { + return controller.Actions.Values + .First(a => a.Name == actionName + "Async" || a.Name == actionName); + } +} diff --git a/framework/test/Volo.Abp.TestApp/Volo.Abp.TestApp.csproj b/framework/test/Volo.Abp.TestApp/Volo.Abp.TestApp.csproj index ae0b3923a3..d5c3970ddc 100644 --- a/framework/test/Volo.Abp.TestApp/Volo.Abp.TestApp.csproj +++ b/framework/test/Volo.Abp.TestApp/Volo.Abp.TestApp.csproj @@ -6,6 +6,7 @@ net10.0 true + true diff --git a/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/DocumentedAppService.cs b/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/DocumentedAppService.cs new file mode 100644 index 0000000000..477de737e0 --- /dev/null +++ b/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/DocumentedAppService.cs @@ -0,0 +1,40 @@ +using System.ComponentModel; +using System.ComponentModel.DataAnnotations; +using System.Threading.Tasks; +using Volo.Abp.Application.Services; +using Volo.Abp.TestApp.Application.Dto; + +namespace Volo.Abp.TestApp.Application; + +/// +/// A documented application service for testing API descriptions. +/// +/// +/// This service is used in integration tests to verify XML doc extraction. +/// +[Description("Documented service description from attribute")] +[Display(Name = "Documented Service")] +public class DocumentedAppService : ApplicationService, IDocumentedAppService +{ + /// + /// Gets a greeting message for the specified name. + /// + /// The name of the person to greet. + /// A personalized greeting message. + [Description("Get greeting description from attribute")] + [Display(Name = "Get Greeting")] + public Task GetGreetingAsync(string name) + { + return Task.FromResult($"Hello, {name}!"); + } + + /// + /// Creates a documented item. + /// + /// The input for creating a documented item. + /// The created documented item. + public Task CreateAsync(DocumentedDto input) + { + return Task.FromResult(input); + } +} diff --git a/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/Dto/DocumentedDto.cs b/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/Dto/DocumentedDto.cs new file mode 100644 index 0000000000..56119f7939 --- /dev/null +++ b/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/Dto/DocumentedDto.cs @@ -0,0 +1,25 @@ +using System.ComponentModel; +using System.ComponentModel.DataAnnotations; + +namespace Volo.Abp.TestApp.Application.Dto; + +/// +/// A documented DTO for testing type and property descriptions. +/// +[Description("Documented DTO description from attribute")] +[Display(Name = "Documented DTO")] +public class DocumentedDto +{ + /// + /// The name of the documented item. + /// + [Description("Name description from attribute")] + [Display(Name = "Item Name")] + public string Name { get; set; } = default!; + + /// + /// The value of the documented item. + /// + [Description("Value description from attribute")] + public int Value { get; set; } +} diff --git a/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/IDocumentedAppService.cs b/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/IDocumentedAppService.cs new file mode 100644 index 0000000000..2477c2d601 --- /dev/null +++ b/framework/test/Volo.Abp.TestApp/Volo/Abp/TestApp/Application/IDocumentedAppService.cs @@ -0,0 +1,28 @@ +using System.Threading.Tasks; +using Volo.Abp.Application.Services; +using Volo.Abp.TestApp.Application.Dto; + +namespace Volo.Abp.TestApp.Application; + +/// +/// A documented application service for testing API descriptions. +/// +/// +/// This service is used in integration tests to verify XML doc extraction. +/// +public interface IDocumentedAppService : IApplicationService +{ + /// + /// Gets a greeting message for the specified name. + /// + /// The name of the person to greet. + /// A personalized greeting message. + Task GetGreetingAsync(string name); + + /// + /// Creates a documented item. + /// + /// The input for creating a documented item. + /// The created documented item. + Task CreateAsync(DocumentedDto input); +}