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.

Note

When an operation defines an OperationId, it is used to derive the contract class name. If it doesn’t, the name is derived from the HTTP method plus the literal (non-parameter) path segments (e.g. GET /v1/entity/{id}/live → GetV1EntityLiveHttpRequest). Two operation-id-less paths that would otherwise collide — such as /entity/{id}/schedule and /entity/{id}/schedule/{year}/{month} — are disambiguated automatically by appending the trailing path parameters (GetV1EntityScheduleHttpRequest and GetV1EntityScheduleByYearMonthHttpRequest). Providing meaningful operation IDs still yields the clearest names.

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 when present; otherwise the name is derived from the HTTP method and path segments (see the note under Overview). Meaningful operation IDs still produce the clearest names.
• Response and request-body schemas that are defined inline (an anonymous object rather than a $ref to a named component schema) are given a synthesized, strongly-typed contract (e.g. GetUsersResponse) instead of falling back to a weakly-typed object.