OpenAPI Contract Generation

Shiny Mediator can generate HTTP request contracts and response types directly from an OpenAPI (Swagger) specification. This eliminates the need to manually write contracts for APIs that already have an OpenAPI document.

Overview

If your API already has an OpenAPI spec, you don’t need to hand-write IHttpRequest<T> contracts for every endpoint. Instead, add a <MediatorHttp> MSBuild item to your project and Shiny Mediator’s source generator will produce all the contracts and response types at build time.

If there is no OperationId defined for an OpenAPI method, a contract cannot be generated for that endpoint. Ensure your OpenAPI spec includes operation IDs.

Setup

1. Ensure Shiny.Mediator is installed in your project

2. Add a <MediatorHttp> item to your .csproj file pointing to your OpenAPI document

   From a local file:

   <ItemGroup>
       <MediatorHttp Include="OpenApiDoc.json"
                     Namespace="MyApp.Api"
                     ContractPostfix="HttpRequest"
                     Visible="false" />
   </ItemGroup>

   From a remote URI:

   <ItemGroup>
       <MediatorHttp Include="OpenApiRemote"
                     Uri="https://api.myapp.com/swagger/v1/swagger.json"
                     Namespace="MyApp.Api"
                     ContractPostfix="HttpRequest"
                     Visible="false" />
   </ItemGroup>

3. Register the generated client in your service configuration

   builder.Services.AddShinyMediator(x => x.AddGeneratedOpenApiClient());

   Note

   The .AddGeneratedOpenApiClient() method will only exist if OpenAPI handlers have been generated. It registers all MediatorHttp elements in that library.

4. Build your project - contracts are generated automatically

5. Use the generated contracts like any other HTTP request

   var result = await mediator.Request(new GetUsersHttpRequest
   {
       Page = 1,
       PageSize = 25
   });

MSBuild Attributes Reference

Attribute	Required	Description
Include	Yes	The local file path to the OpenAPI document, or a placeholder name when using Uri
Uri	No	A remote URL to fetch the OpenAPI document from. When set, Include is still required but serves as an identifier
Namespace	Yes	The C# namespace for the generated contracts
ContractPrefix	No	Text prepended to each generated contract name
ContractPostfix	No	Text appended to each generated contract name (e.g. "HttpRequest")
Visible	No	Set to "false" to hide the item from the IDE solution explorer. Recommended when using Uri
GenerateJsonConverters	No	Set to "true" to source-generate JSON converters for AOT scenarios. See Configuration & AOT

Example Configuration

<ItemGroup>
    <!-- Local OpenAPI file -->
    <MediatorHttp Include="specs/products-api.json"
                  Namespace="MyApp.Products"
                  ContractPrefix="Products"
                  ContractPostfix="HttpRequest"
                  Visible="false" />

    <!-- Remote OpenAPI file -->
    <MediatorHttp Include="UsersApi"
                  Uri="https://api.myapp.com/swagger/v1/swagger.json"
                  Namespace="MyApp.Users"
                  ContractPostfix="HttpRequest"
                  Visible="false" />
</ItemGroup>

Notes and Limitations

• When using the Uri attribute, you must still set the Include value to satisfy the MSBuild ItemGroup requirements. Use Visible="false" to hide it from the IDE solution explorer.
• There are scenarios not yet supported, such as discriminated types. These are being evaluated for future implementation.
• The OperationId is used to derive the contract class name. Ensure your OpenAPI spec defines meaningful operation IDs for clear contract names.