OpenApiMediatRResponseMatcher 1.0.5

OpenAPI MediatR Response Matcher

A .NET global tool that automatically detects mismatches between ASP.NET Core controller ActionResult<T> return types and MediatR handler response types. Ensures your Swagger/OpenAPI documentation matches your actual API responses.

GitHub Repository: https://github.com/BekirK-C/OpenApiMediatRResponseMatcher

Why Use This Tool?

When using the MediatR pattern, developers often:

• Forget to declare return types in ActionResult<T> for Swagger documentation
• Declare wrong return types when handlers are updated
• Have documentation that doesn't match actual API behavior

This tool scans your codebase and finds these issues automatically.

Installation

dotnet tool install -g OpenApiMediatRResponseMatcher

First-Time Setup (PATH Configuration)

After installation, if the command is not found, you need to add .NET tools to your PATH:

macOS/Linux:

# Add to ~/.zshrc (macOS) or ~/.bashrc (Linux)
echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell):

# Add to PowerShell profile
Add-Content $PROFILE "`n`$env:PATH += ';$env:USERPROFILE\.dotnet\tools'"
# Restart PowerShell or run:
. $PROFILE

Windows (Command Prompt):

• Add %USERPROFILE%\.dotnet\tools to your System PATH environment variable
• Restart Command Prompt

After setup, verify installation:

openapi-mediatr-matcher --help

Quick Start

# Easiest way: Navigate to your project folder and run
openapi-mediatr-matcher --mismatches-only

# Or specify project path explicitly
openapi-mediatr-matcher --project "/path/to/your/api" --mismatches-only

# Custom paths (if auto-detection fails)
openapi-mediatr-matcher --controllers "src/Api" --handlers "src/Application"

Command Options

Note: Most projects only need --mismatches-only. Just navigate to your project folder and run the command. Use --project only if running from a different location. Use --controllers and --handlers only for non-standard project structures or custom MediatR wrappers.

Example Output

Controller-Handler OpenAPI Analysis Report
==========================================

Total Actions Analyzed: 45
  [OK] Correct: 38
  [XX] Total Mismatches: 7
    - Missing Type Parameter: 4
    - Wrong Type Parameter: 2

[XX] ReservationsController.GetById()
   Location: src/Api/Controllers/ReservationsController.cs:42
   Declared: Task<ActionResult>
   Handler:  GetReservationByIdQueryHandler
   Returns:  ReservationDetailDto
   Issue:    Type mismatch: ActionResult missing type parameter
   Fix:      Change return type to: Task<ActionResult<ReservationDetailDto>>

Detected Mismatch Types

1. Missing Type Parameter - Controller returns ActionResult but handler returns data
2. Wrong Type Parameter - Type in ActionResult<T> doesn't match handler response
3. Unnecessary Type Parameter - Controller has ActionResult<T> but handler returns void
4. Handler Not Found - No handler found for the request type
5. Request Type Not Found - Cannot determine MediatR request from controller

Supported Patterns

The tool automatically detects these MediatR patterns:

// Standard MediatR
await _mediator.Send(new GetQuery());

// Custom executors
await CommandQueryExecutor.ExecuteQueryAsync(new GetQuery());
await CommandQueryExecutor.ExecuteCommandAsync(new CreateCommand());

// Method chaining
await Executor.Send(new Command().SetId(id).SetName(name));

Module-Aware Duplicate Handlers

When multiple handlers exist for the same request type (e.g., in different modules), the tool automatically matches controllers to handlers from the same module.

Requirements

• .NET 9.0 or higher
• Projects using MediatR pattern
• ASP.NET Core controllers with ActionResult return types

Update

dotnet tool update -g OpenApiMediatRResponseMatcher

Uninstall

dotnet tool uninstall -g OpenApiMediatRResponseMatcher