Franz.Common.Http.Documentation
3.0.2
dotnet add package Franz.Common.Http.Documentation --version 3.0.2
NuGet\Install-Package Franz.Common.Http.Documentation -Version 3.0.2
<PackageReference Include="Franz.Common.Http.Documentation" Version="3.0.2" />
<PackageVersion Include="Franz.Common.Http.Documentation" Version="3.0.2" />
<PackageReference Include="Franz.Common.Http.Documentation" />
paket add Franz.Common.Http.Documentation --version 3.0.2
#r "nuget: Franz.Common.Http.Documentation, 3.0.2"
#:package Franz.Common.Http.Documentation@3.0.2
#addin nuget:?package=Franz.Common.Http.Documentation&version=3.0.2
#tool nuget:?package=Franz.Common.Http.Documentation&version=3.0.2
Franz.Common.Http.Documentation
ASP.NET Core URL-segment API versioning and native OpenAPI/Scalar endpoint registration.
Overview
This package configures API versioning and native OpenAPI/Scalar endpoint registration for Franz HTTP services.
Installation
dotnet add package Franz.Common.Http.Documentation
Service registration
The fluent builder is defined in Franz.Common.Http.Documentation.Extensions.
using Franz.Common.Http.Documentation.Extensions;
builder.Services
.AddFranzDocumentation()
.ConfigureApiVersioning()
.ConfigureOpenApi();
Call ConfigureApiVersioning() before ConfigureOpenApi(). The standard version reader is exclusively URL-segment based. The default API version is 1.0, the default version is assumed when unspecified, and supported API versions are reported.
The standard route prefix is:
/api/v{version:apiVersion}
Client request contract
The API version belongs in the URL. Clients must not use MediaTypeApiVersionWriter, add an x-api-version request header, or encode the version as an Accept media-type parameter.
Send a normal representation preference:
GET /api/v1/orders
Accept: application/json
Do not send:
Accept: application/json; x-api-version=1.0
x-api-version: 1.0
The versioning configuration does not rewrite or sanitize client headers. Applications that explicitly replace the configured ApiVersionReader own that alternative contract and its associated content-negotiation behavior.
OpenAPI registration
The current ConfigureOpenApi() implementation registers the native OpenAPI document named v1. It sets the document title from the entry assembly and the document version to 1.0. Do not assume that it currently discovers and registers one document for every API version: the implementation shown registers only v1.
Endpoint mapping
Call UseDocumentation() from the namespace Franz.Common.Http.Bootstrap.Extensions after the application is built and routing is configured.
using Franz.Common.Http.Bootstrap.Extensions;
app.UseDocumentation();
The extension maps the native OpenAPI endpoint at /openapi/{documentName}.json and Scalar's API reference. The current Scalar configuration exposes the v1 document using /openapi/v1.json.
Restrict documentation endpoints according to the deployment's exposure policy. The extension itself does not enforce a Development-only environment condition.
Route conventions
The versioning registration adds the general route prefix through MVC options. Controllers still need API-version metadata for the versioning explorer to group them correctly.
[ApiController]
[ApiVersion("1.0")]
[Route("orders")]
public sealed class OrdersController : ControllerBase
{
}
Avoid applying a second route-prefix convention manually unless the application intentionally replaces the package's default.
Current implementation boundaries
The project uses ASP.NET Core native OpenAPI and Scalar rather than the legacy Swashbuckle integration described in older package history. The current source still contains historical filenames such as ConfigureSwaggerOptions.cs and SwaggerGenOptionsExtensions.cs; filenames are not a reliable statement of the public API. Verify the active extension signatures in the source before using historical changelog names.
The current document registration is fixed to v1; multi-version document discovery and schema-transformer behavior should not be assumed from earlier README text.
License
MIT. See LICENSE.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Asp.Versioning.Mvc.ApiExplorer (>= 10.0.0)
- Franz.Common.Business (>= 3.0.2)
- Franz.Common.Reflection (>= 3.0.2)
- Microsoft.AspNetCore.OpenApi (>= 10.0.14)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.14)
- Scalar.AspNetCore (>= 2.16.16)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Franz.Common.Http.Documentation:
| Package | Downloads |
|---|---|
|
Franz.Common.Http.Bootstrap
Shared utility library for the Franz Framework. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 3.0.2 | 0 | 11/20/2026 |
| 3.0.1 | 0 | 11/19/2026 |
| 3.0.0 | 116 | 11/10/2026 |
| 2.3.4 | 350 | 11/1/2026 |
| 2.3.3 | 320 | 10/28/2026 |
| 2.3.2 | 115 | 10/27/2026 |
| 2.3.1 | 175 | 10/26/2026 |
| 2.3.0 | 249 | 7/21/2026 |
| 2.2.19 | 142 | 7/19/2026 |
| 2.2.18 | 146 | 7/19/2026 |
| 2.2.17 | 135 | 7/12/2026 |
| 2.2.16 | 161 | 7/2/2026 |
| 2.2.15 | 145 | 6/29/2026 |
| 2.2.14 | 145 | 6/29/2026 |
| 2.2.13 | 145 | 6/29/2026 |
| 2.2.12 | 136 | 6/28/2026 |
| 2.2.11 | 135 | 6/28/2026 |
| 2.2.10 | 147 | 6/28/2026 |
| 2.2.9 | 143 | 6/28/2026 |
| 2.2.8 | 135 | 6/28/2026 |