SourceGenerator & DiagnosticAnalyzer

- improving source generator - add diagnostic warning for non-empty constructor on WebApiEndpoint
- add Analyzer to warn for non-empty constructor on WebApiEndpoint
- add Analyzer to warn if a BadRequest is returned that does not contain a ProblemDetails on WebApiEndpoint

Author: futurum-dev

README.md

@@ -28,18 +28,19 @@ public class GreetingWebApiEndpoint : IWebApiEndpoint
 - [x] Vertical Slice Architecture, gives you the ability to add new features without changing existing code
 - [x] Structured way of building WebApiEndpoints using [minimal apis](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis?view=aspnetcore-7.0)
 - [x] [Easy setup](#easy-setup)
-- [x] Developer friendly 
+- [x] Developer friendly, with a simple API and with a full suite of samples and tests
 - [x] Full support and built on top of [minimal apis](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis?view=aspnetcore-7.0)
 - [x] Full support for OpenApi
 - [x] Full support for [TypedResults](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.typedresults?view=aspnetcore-7.0)
 - [x] [Full compatibility](#full-compatibility-with-futurumcore) with [Futurum.Core](https://www.nuget.org/packages/Futurum.Core)
-- [x] [Supports uploading file(s) with additional JSON payload](#uploading-file--s--with-additional-json-payload)
+- [x] [Supports uploading file(s) with additional JSON payload](#uploading-files-with-additional-json-payload)
 - [x] Api Versioning baked-in
 - [x] Built in [sandbox runner](#sandbox-runner) with full [TypedResults support](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.typedresults?view=aspnetcore-7.0), catching unhandled exceptions and returning a [ProblemDetails](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.problemdetails?view=aspnetcore-7.0) response
 - [x] [Built in Validation support](#validation)
   - [x] [Integrated FluentValidation](#fluentvalidationservice)
   - [x] [Integrated DataAnnotations](#dataannotationsvalidationservice)
 - [x] Autodiscovery of WebApiEndpoint(s), based on Source Generators
+- [x] [Roslyn Analysers](#roslyn-analysers) to help build your WebApiEndpoint(s), using best practices
 - [x] Built on dotnet 7
 - [x] Built in use of [ProblemDetails](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.problemdetails?view=aspnetcore-7.0) support
 - [x] [Tested solution](https://coveralls.io/github/futurum-dev/dotnet.futurum.webapiendpoint.micro)
@@ -596,7 +597,7 @@ There are examples showing the following:
 - [x] Weather Forecast
 - [x] Addition project containing WebApiEndpoints
 
-![Futurum.WebApiEndpoint.Micro.Sample-openapi.png](docs/Futurum.WebApiEndpoint.Micro.Sample-openapi.png)
+![Futurum.WebApiEndpoint.Micro.Sample-openapi.png](https://github.com/futurum-dev/dotnet.futurum.webapiendpoint.micro/raw/main/docs/Futurum.WebApiEndpoint.Micro.Sample-openapi.png)
 
 ## Convention Customisation
 Although the default conventions are good enough for most cases, you can customise them.
@@ -653,4 +654,8 @@ This uses the following attributes:
 
 ```csharp
 [WebApiEndpointVersion(1)]
-```
+```
+
+## Roslyn Analysers
+- FWAEM0001 - Non empty constructor found on WebApiEndpoint
+- FWAEM0002 - BadRequest without 'ProblemDetails' use found on WebApiEndpoint

docs/Futurum.WebApiEndpoint.Micro.Sample-openapi.png

@@ -0,0 +1,13 @@
+namespace Futurum.WebApiEndpoint.Micro.Sample.Analyzers;
+
+[WebApiEndpoint(prefixRoute: "method-returning-BadRequest-without-ProblemDetails", group: "analyzer")]
+public class MethodReturningBadRequestWithoutProblemDetails : IWebApiEndpoint
+{
+    public void Register(IEndpointRouteBuilder builder)
+    {
+        builder.MapGet("/", ResultErrorHandler);
+    }
+    
+    private static Results<Ok<string>, BadRequest<string>> ResultErrorHandler(HttpContext context) =>
+        "This WebApiEndpoint has a non-empty constructor and will raise a warning.".ToOk();
+}

sample/Futurum.WebApiEndpoint.Micro.Sample/Analyzers/MethodReturningBadRequestWithoutProblemDetails.cs

@@ -0,0 +1,17 @@
+namespace Futurum.WebApiEndpoint.Micro.Sample.Analyzers;
+
+[WebApiEndpoint("non-empty-constructor", "analyzer")]
+public class NonEmptyConstructorOnWebApiEndpoint : IWebApiEndpoint
+{
+    public NonEmptyConstructorOnWebApiEndpoint(IConfiguration configuration)
+    {
+    }
+    
+    public void Register(IEndpointRouteBuilder builder)
+    {
+        builder.MapGet("/", GetHandler);
+    }
+
+    private static Ok<string> GetHandler(HttpContext context) =>
+        "This WebApiEndpoint has a non-empty constructor and will raise a warning.".ToOk();
+}

sample/Futurum.WebApiEndpoint.Micro.Sample/Analyzers/NonEmptyConstructorOnWebApiEndpoint.cs

@@ -0,0 +1,24 @@
+using Microsoft.CodeAnalysis;
+
+namespace Futurum.WebApiEndpoint.Micro.Generator;
+
+public static class DiagnosticDescriptors
+{
+    public static readonly DiagnosticDescriptor WebApiEndpointNonEmptyConstructor = new(
+        "FWAEM0001",
+        "Non empty constructor found on WebApiEndpoint",
+        $"WebApiEndpoint class '{{0}}' does not have an empty constructor.{Environment.NewLine}" +
+        $"We recommend that WebApiEndpoint's have an empty constructor and to take any injectable dependencies as parameters via the minimal API method itself.{Environment.NewLine}" +
+        $"Constructor dependencies will have a lifetime outside of the minimal API lifetime and could have unintended consequences.",
+        "Futurum.WebApiEndpoint.Micro.Generator",
+        DiagnosticSeverity.Warning,
+        true);
+
+    public static readonly DiagnosticDescriptor WebApiEndpointMethodReturningBadRequestWithoutProblemDetails = new(
+        "FWAEM0002",
+        "BadRequest without 'ProblemDetails' use found on WebApiEndpoint",
+        "Minimal API methods returning a 'BadRequest', should ensure that the 'BadRequest' is created with a 'ProblemDetails' instance.",
+        "Futurum.WebApiEndpoint.Micro.Generator",
+        DiagnosticSeverity.Warning,
+        true);
+}

src/Futurum.WebApiEndpoint.Micro.Generator/DiagnosticDescriptors.cs

@@ -0,0 +1,58 @@
+using Microsoft.CodeAnalysis;
+
+namespace Futurum.WebApiEndpoint.Micro.Generator;
+
+public static class Diagnostics
+{
+    public static INamedTypeSymbol? GetWebApiEndpointInterfaceType(Compilation semanticModelCompilation) =>
+        semanticModelCompilation.GetTypeByMetadataName("Futurum.WebApiEndpoint.Micro.IWebApiEndpoint");
+
+    public static class WebApiEndpointNonEmptyConstructor
+    {
+        public static IEnumerable<Diagnostic> Check(INamedTypeSymbol classSymbol)
+        {
+            foreach (var classSymbolConstructor in classSymbol.Constructors)
+            {
+                var emptyConstructor = !classSymbolConstructor.Parameters.Any();
+
+                if (!emptyConstructor)
+                {
+                    yield return Diagnostic.Create(DiagnosticDescriptors.WebApiEndpointNonEmptyConstructor,
+                                                   classSymbolConstructor.Locations.First(),
+                                                   classSymbol.ToDisplayString(SymbolDisplayFormat.CSharpErrorMessageFormat));
+                }
+            }
+        }
+    }
+
+    public static class WebApiEndpointMethodReturningBadRequestWithoutProblemDetails
+    {
+        public static IEnumerable<Diagnostic> Check(IMethodSymbol methodSymbol)
+        {
+            var returnType = methodSymbol.ReturnType;
+
+            if (!returnType.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat).StartsWith("global::Microsoft.AspNetCore.Http.HttpResults.Results"))
+                yield break;
+
+            if (returnType is not INamedTypeSymbol namedTypeSymbol)
+                yield break;
+
+            foreach (var typeSymbol in namedTypeSymbol.TypeArguments)
+            {
+                if (typeSymbol.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat).StartsWith("global::Microsoft.AspNetCore.Http.HttpResults.BadRequest"))
+                {
+                    if (typeSymbol is INamedTypeSymbol typeSymbolOriginalDefinition)
+                    {
+                        var returnTypeArgument = typeSymbolOriginalDefinition.TypeArguments.First();
+
+                        if (returnTypeArgument.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat) != "global::Microsoft.AspNetCore.Mvc.ProblemDetails")
+                        {
+                            yield return Diagnostic.Create(DiagnosticDescriptors.WebApiEndpointMethodReturningBadRequestWithoutProblemDetails,
+                                                           methodSymbol.Locations.First());
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

src/Futurum.WebApiEndpoint.Micro.Generator/Diagnostics.cs

@@ -5,12 +5,14 @@
         <ImplicitUsings>enable</ImplicitUsings>
         <Nullable>enable</Nullable>
         <LangVersion>10</LangVersion>
+        <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
+        <BuildOutputTargetFolder>analyzers</BuildOutputTargetFolder>
         <IncludeBuildOutput>false</IncludeBuildOutput>
         <IsRoslynComponent>true</IsRoslynComponent>
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.4.0"/>
+        <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.4.0" />
         <PackageReference Include="ThisAssembly" Version="1.2.12" PrivateAssets="all" />
     </ItemGroup>
 

src/Futurum.WebApiEndpoint.Micro.Generator/Futurum.WebApiEndpoint.Micro.Generator.csproj

@@ -0,0 +1,38 @@
+using System.Collections.Immutable;
+
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.Diagnostics;
+
+namespace Futurum.WebApiEndpoint.Micro.Generator;
+
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public class WebApiEndpointMethodReturningBadRequestWithoutProblemDetailsAnalyzer : DiagnosticAnalyzer
+{
+    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; }
+        = ImmutableArray.Create(DiagnosticDescriptors.WebApiEndpointMethodReturningBadRequestWithoutProblemDetails);
+
+    public override void Initialize(AnalysisContext context)
+    {
+        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+        context.EnableConcurrentExecution();
+
+        context.RegisterSymbolAction(Execute, SymbolKind.Method);
+    }
+
+    private static void Execute(SymbolAnalysisContext context)
+    {
+        if (context.Symbol is not IMethodSymbol methodSymbol)
+            return;
+
+        var webApiEndpointInterfaceType = Diagnostics.GetWebApiEndpointInterfaceType(context.Compilation);
+        if (methodSymbol.ContainingType.AllInterfaces.Contains(webApiEndpointInterfaceType))
+        {
+            var diagnostics = Diagnostics.WebApiEndpointMethodReturningBadRequestWithoutProblemDetails.Check(methodSymbol);
+
+            foreach (var diagnostic in diagnostics)
+            {
+                context.ReportDiagnostic(diagnostic);
+            }
+        }
+    }
+}

src/Futurum.WebApiEndpoint.Micro.Generator/WebApiEndpointMethodReturningBadRequestWithoutProblemDetailsAnalyzer.cs

@@ -0,0 +1,43 @@
+using System.Collections.Immutable;
+
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.Diagnostics;
+
+namespace Futurum.WebApiEndpoint.Micro.Generator;
+
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public class WebApiEndpointNonEmptyConstructorAnalyzer : DiagnosticAnalyzer
+{
+    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; }
+        = ImmutableArray.Create(DiagnosticDescriptors.WebApiEndpointNonEmptyConstructor);
+
+    public override void Initialize(AnalysisContext context)
+    {
+        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+        context.EnableConcurrentExecution();
+
+        context.RegisterSymbolAction(Execute, SymbolKind.NamedType);
+    }
+
+    private static void Execute(SymbolAnalysisContext context)
+    {
+        if (context.Symbol is not INamedTypeSymbol classSymbol)
+            return;
+
+        var webApiEndpointInterfaceType = Diagnostics.GetWebApiEndpointInterfaceType(context.Compilation);
+        if (webApiEndpointInterfaceType is not null)
+        {
+            var implementsInterface = classSymbol.AllInterfaces.Contains(webApiEndpointInterfaceType);
+
+            if (implementsInterface)
+            {
+                var diagnostics = Diagnostics.WebApiEndpointNonEmptyConstructor.Check(classSymbol);
+
+                foreach (var diagnostic in diagnostics)
+                {
+                    context.ReportDiagnostic(diagnostic);
+                }
+            }
+        }
+    }
+}

src/Futurum.WebApiEndpoint.Micro.Generator/WebApiEndpointNonEmptyConstructorAnalyzer.cs

@@ -21,15 +21,21 @@ public static bool SemanticPredicate(SyntaxNode node, CancellationToken ct) =>
         var classDeclaration = (ClassDeclarationSyntax)context.Node;
         var semanticModel = context.SemanticModel;
         var classSymbol = semanticModel.GetDeclaredSymbol(classDeclaration, ct);
-        var interfaceTypeSymbol = semanticModel.Compilation.GetTypeByMetadataName("Futurum.WebApiEndpoint.Micro.IWebApiEndpoint");
-        if (classSymbol is not null && interfaceTypeSymbol is not null)
+
+        var webApiEndpointInterfaceType = Diagnostics.GetWebApiEndpointInterfaceType(semanticModel.Compilation);
+
+        if (classSymbol is not null && webApiEndpointInterfaceType is not null)
         {
-            var implementsInterface = classSymbol.AllInterfaces.Contains(interfaceTypeSymbol);
+            var implementsInterface = classSymbol.AllInterfaces.Contains(webApiEndpointInterfaceType);
 
             if (implementsInterface)
             {
+                var diagnostics = new List<Diagnostic>();
+                diagnostics.AddRange(Diagnostics.WebApiEndpointNonEmptyConstructor.Check(classSymbol));
+
                 var webApiEndpointData = new WebApiEndpointDatum(classSymbol.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat));
-                return new WebApiEndpointContext(webApiEndpointData: new[] { webApiEndpointData });
+
+                return new WebApiEndpointContext(diagnostics, new[] { webApiEndpointData });
             }
         }