Repository navigation
Releases
1.0.0
First stable release of Hlibz.OpenApi.AspNetCore: transformers for Microsoft.AspNetCore.OpenApi (AddOpenApi() / MapOpenApi()), for .NET 10 and 11.
Same code as 1.0.0-preview.6. No package changes since that preview. The preview releases describe how the API got here.
Changes
- The
Atlas.Apisample is built on Hlibz.MinimalApi.Endpoints 1.0.0.
Package
Full changelog: v1.0.0-preview.6...v1.0.0
1.0.0-preview.6
Features
AddXmlDocumentation()publishes each enum value's<summary>inx-enumDescriptionson the enum's schema, which ReDoc and Scalar show as a table of values. Keys follow the schema'senumlist: JSON names (afterJsonStringEnumConverter's naming policy and[JsonStringEnumMemberName]), numbers for an integer enum, or declared names where a query parameter's schema lists those. Every value is listed, an undocumented one with an empty description, because ReDoc shows this list in place ofenum.
Package
1.0.0-preview.5
Fifth preview: built with runtime async on .NET 11.
Changes
- Runtime async on .NET 11. The net11.0 build compiles its async methods with runtime async (
runtime-async=on), the way the .NET 11 libraries themselves are compiled: no compiler state machine, cheaper suspension inside ASP.NET Core's own async chains, and clearer async stack traces. The net10.0 build is unchanged. It covers the schema and operation transformers.
No API changes.
Packages
Full changelog: v1.0.0-preview.4...v1.0.0-preview.5
1.0.0-preview.4
Fourth preview: faster document generation, and the package is AOT-compatible.
Changes
- Less reflection per document. Rule attributes, single-value structs (strongly-typed IDs), collection element types and the search for validation rules are looked up once per type or member instead of on every schema and operation.
- Lighter XML documentation reading.
AddXmlDocumentation()streams each XML file and keeps only type and property (T:/P:) members. Method, field and event docs are no longer parsed or held in memory. - AOT-compatible.
IsAotCompatibleis on, and the package builds without trimming or AOT warnings. A rule attribute instance is shared by every document, soIOpenApiRule.Describemust not change the rule. - Docs: a new "Performance and AOT" section recommends caching the served document with output caching (
app.MapOpenApi().CacheOutput()), since transformers run on every request for it. The Atlas.Api sample does this.
No API changes.
Packages
Full changelog: v1.0.0-preview.3...v1.0.0-preview.4
1.0.0-preview.3
Third preview: two fixes for apps that use the package in ways the tests didn't cover.
Fixes
- Apps that install only this package compile. NuGet passes Microsoft.AspNetCore.OpenApi's XML comment generator on to an app that gets it only through Hlibz.OpenApi.AspNetCore, but not the build targets that allow the generator's interceptors, so such an app failed with CS9137. The package now ships
buildTransitive/Hlibz.OpenApi.AspNetCore.targets, which allows them. Apps that also reference Microsoft.AspNetCore.OpenApi directly are unaffected. AddXmlDocumentation()works in single-file apps. Assemblies bundled into a single file have no location, so no XML file was found and nothing was described. It now looks for the XML files in the app's directory (AppContext.BaseDirectory), where publish puts them.RuleTextno longer goes through the trim-unsafeJsonArray.Add<T>.
Changes
- CI builds an app from the packed package that references only Hlibz.OpenApi.AspNetCore, runs it as a normal build and as a single-file publish, and checks that a type from another project is described.
- Docs: Microsoft's generator skips
internaltypes on .NET 10 but covers them on .NET 11. - The Atlas.Api sample uses Hlibz.MinimalApi.Endpoints 1.0.0-preview.5.
No API changes.
Packages
Full changelog: v1.0.0-preview.2...v1.0.0-preview.3
1.0.0-preview.2
Second preview, with fixes from adopting 1.0.0-preview.1 in a real API.
Breaking changes
AddStronglyTypedIdstakes options. A custom rule moves from the parameter toValueTypeOf:
options.AddStronglyTypedIds(ids => ids.ValueTypeOf = type => ...).
Features
-
AddXmlDocumentation()publishes XML<summary>comments as the descriptions of schemas, their properties and[AsParameters]parameters, reading each assembly's XML file at runtime. Unlike Microsoft.AspNetCore.OpenApi's own XML comment generator, it:- covers
internaltypes, such as request bodies and query classes; - covers types from other projects, and from NuGet packages when the app sets
CopyDocumentationFilesFromPackages; - writes a
<see cref>as the name it refers to, without the member's type before it; - puts each summary on one line;
- reads a record's
<param>tags for its positional properties.
It replaces the generator's descriptions where it has a summary, keeps the text
AddOpenApiRules()writes after it whichever is registered first, and leaves operations alone. - covers
-
AddStronglyTypedIds(ids => ids.AsComponents = true)keeps each ID a component of its own (CountryId:{ "type": "string", "format": "uuid" }) that properties point at with$ref, so clients generated against the ID types' names keep working. Nullable uses becomeoneOfwithnull; parameters stay inline.
Docs
OPENAPI_PACKAGE_FINDINGS.mdcorrects its verdict that the built-in generator covers XML comments.- The Atlas.Api sample uses
AddXmlDocumentation(), with an internal request type to show it.
Packages
Full changelog: v1.0.0-preview.1...v1.0.0-preview.2
1.0.0-preview.1
First preview of Hlibz.OpenApi.AspNetCore: transformers for Microsoft.AspNetCore.OpenApi (AddOpenApi() / MapOpenApi()), for .NET 10 and 11.
Features
AddOpenApiRules(): custom validation attributes describe themselves (IOpenApiRule), writing their own schema keywords plus text indescriptionandx-rules;[OpenApiRule("...")]for rules in words only.AddStronglyTypedIds():CountryId(Guid Value)is published as auuidstring, inlined, with noCountryIdcomponent.AddValidationProblems(): the400(HttpValidationProblemDetails) thatAddValidation()answers with, on exactly the operations it can come from.AddBearerSecurity()/AddSecurity(name, scheme): a lock on exactly the endpoints that require authorization.AddDescriptionCleanup(): "Gets or sets the name." reads "The name." in schema and parameter descriptions.services.AddOpenApiDocuments(...): one document per endpoint group, configured once.
The Atlas.Api sample shows every feature, on Hlibz.MinimalApi.Endpoints 1.0.0-preview.4 and Hlibz.Redoc.AspNetCore.