• Unlocked Api
  • Table of Contents
  • Generate OpenAPI on build
    • Remarks
  • OpenApi schema possible mismatches
    • MVC Controllers
    • null is valid on non-nullable reference types, unless
    • Constructor parameters are optional by default
    • Required properties
    • DataAnnotations with Minimal APIs before .NET 10
  • .NET 10 Preview 3 bugs
  • Describing API Responses
  • Enums
  • Insert and reference custom schemas
  • Spectral OpenApi Linting

See: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-10.0&tabs=net-cli%2Cvisual-studio-code#generate-openapi-documents-at-build-time

dotnet add package Microsoft.Extensions.ApiDescription.Server

Settings in csproj:

<PropertyGroup>
  <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>
  <OpenApiGenerateDocumentsOptions>--file-name openapi</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

.yaml on build is not yet supported in .NET 10.

The default document is v1. This will be in the output without suffix. See dotnet/aspnetcore#58782.

Documents not matching v1 will be in the output as {file-name}_{doc-name}. For example for v2 and filename openapi the resulting file is openapi_v2.json, where the v1 document will be called openapi.json.

As OpenAPI generates schemas, they can give you a false sense of security. The generated schemas are not always correct.

ASP.NET Core OpenApi will use the Http.JsonOptions as the json configuration for generating schemas. Where MVC has different JsonOptions, so when using MVC Controllers with custom JsonSerializerOptions the changes need to be replicated to the Http.JsonOptions.

The generated schemas will tell that null is not valid on non-nullable reference types. This is correct, but System.Text.Json does not enforce this by default. You can set the JsonSerializerOptions to enforce this.

Global:

<ItemGroup>
  <RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.RespectNullableAnnotationsDefault" Value="true" />
</ItemGroup>

Local:

JsonSerializerOptions options = new()
{
    RespectNullableAnnotations = true
};

Record/class constructor parameters are optional by System.Text.Json (resulting in the default). The schema will show that the constructor parameters are required, but the deserialization will not enforce this. You can set the JsonSerializerOptions to enforce this.

Global:

<ItemGroup>
  <RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault" Value="true" />
</ItemGroup>

Local:

JsonSerializerOptions options = new()
{
    RespectRequiredConstructorParameters = true
};

This works as expected. Both the schema will show that it's required and the deserialization will enforce this.

DataAnnotations are used by OpenApi to enrich the schema. But by default, Minimal APIs do NOT Validate. In .NET 10 you can enable this.

From release notes preview 3: https://github.com/dotnet/core/blob/main/release-notes/10.0/preview/preview3/aspnetcore.md#validation-support-in-minimal-apis

csproj:

<PropertyGroup>
  <!-- Enable the generation of interceptors for the validation attributes -->
  <InterceptorsNamespaces>$(InterceptorsNamespaces);Microsoft.AspNetCore.Http.Validation.Generated</InterceptorsNamespaces>
</PropertyGroup>

Program.cs:

builder.Services.AddValidation();

Explicit Metadata Added to the builder

.Produces<UnlockResponse>(StatusCodes.Status200OK)
.Produces(StatusCodes.Status404NotFound);

Metadata from Results:

Results<Ok<UnlockResponse>, NotFound>

Enums by default are serialized as numbers. Configure in JsonSerializerOptions (Http.JsonOptions).

See community standup -> https://youtu.be/oqAowFs5zZQ?t=3176

Install with Node

npm install --save -D @stoplight/spectral-cli
npm install --save -D @stoplight/spectral-url-versioning

.spectral.yml

extends: ["spectral:oas", "@stoplight/spectral-url-versioning"]