Skip to content

Releases

1.0.0

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 18 Nov 07:59

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.Api sample 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

1.0.0-preview.6 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 17 Nov 08:20

Features

  • AddXmlDocumentation() publishes each enum value's <summary> in x-enumDescriptions on the enum's schema, which ReDoc and Scalar show as a table of values. Keys follow the schema's enum list: JSON names (after JsonStringEnumConverter'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 of enum.

Package

1.0.0-preview.5

1.0.0-preview.5 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 14 Nov 16:27

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

1.0.0-preview.4 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 14 Nov 08:05

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. IsAotCompatible is on, and the package builds without trimming or AOT warnings. A rule attribute instance is shared by every document, so IOpenApiRule.Describe must 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

1.0.0-preview.3 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 13 Nov 19:46

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.
  • RuleText no longer goes through the trim-unsafe JsonArray.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 internal types 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

1.0.0-preview.2 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 13 Nov 17:15

Second preview, with fixes from adopting 1.0.0-preview.1 in a real API.

Breaking changes

  • AddStronglyTypedIds takes options. A custom rule moves from the parameter to ValueTypeOf:
    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 internal types, 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.

  • 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 become oneOf with null; parameters stay inline.

Docs

  • OPENAPI_PACKAGE_FINDINGS.md corrects 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

1.0.0-preview.1 Pre-release
Pre-release

Choose a tag to compare

@hlib-zinchenko hlib-zinchenko released this 13 Nov 14:23

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 in description and x-rules; [OpenApiRule("...")] for rules in words only.
  • AddStronglyTypedIds(): CountryId(Guid Value) is published as a uuid string, inlined, with no CountryId component.
  • AddValidationProblems(): the 400 (HttpValidationProblemDetails) that AddValidation() 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.

Packages