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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Franz.Common.Http.Documentation" Version="3.0.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Franz.Common.Http.Documentation" Version="3.0.2" />
                    
Directory.Packages.props
<PackageReference Include="Franz.Common.Http.Documentation" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Franz.Common.Http.Documentation --version 3.0.2
                    
#r "nuget: Franz.Common.Http.Documentation, 3.0.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Franz.Common.Http.Documentation@3.0.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Franz.Common.Http.Documentation&version=3.0.2
                    
Install as a Cake Addin
#tool nuget:?package=Franz.Common.Http.Documentation&version=3.0.2
                    
Install as a Cake Tool

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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
Loading failed