How can properties be marked as required when generating Open API JSON?

[tjementum]

We are using NSwag to generate an OpenAPI.json file for our .NET 8 Minimal API. This file is then used by https://openapi-ts.dev/ (openapi-typescript) to generate a TypeScript definition.

Our issue is that the OpenAPI contract is marking all properties as optional, causing the TypeScript contract to mark them as allowing undefined (missing). We want the TypeScript contract to accurately reflect the .NET contract.

Here is our setup:

Program.cs:

var builder = WebApplication.CreateBuilder(args);
app.MapPost("/", User () => new User(1, "Thomas")).Produces<User>();
app.Run();

public record User(long Id, string Name, string? Title = null);

Api.csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)/../WebApp/api/</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="8.0.6">
        <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
      </PackageReference>
    <PackageReference Include="NSwag.MSBuild" Version="14.0.8">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

This is how the generated Api.json looks like:

{
  ...
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "nullable": true
          }
        }
      }
    },
    // The following line is NOT part of the output but that's what we are trying to configure
    "required": [
      "id",
      "name",
      "title" // This is required, even though it allows `null`, which is different from `undefined` (missing)
    ]
  }
}

In the current setup without the required property, this is the types that OpenAPI Typescript is generating (notice that id? and name? is nullable):

export interface components {
  schemas: {
    User: {
      /** Format: int64 */
      id?: number; // Notice that this is optional
      name?: string; // Notice that this is optional
      title?: string | null; // Notice that this is optional but allows null
    };
  };
  ...
}

But if the required property is set, this is what we will get :

export interface components {
  schemas: {
    User: {
      /** Format: int64 */
      id: number; // Notice this now required
      name: string; // Notice this now required
      title?: string | null; // Notice this now required, but still allows null
    };
  };
  ...
}

We believe this might be a bug in NSwag where the required property is not set. In .NET, optional properties can be null, but they are still present. Am I missing something?

Note that we use OpenApiGenerateDocumentsOnBuild in the .csproj file. If a NSwag configuration is needed, how can we use it with OpenApiGenerateDocumentsOnBuild?

[vvdb-architecture]

Did you try either [BindRequired] or [Required] as outlined in https://stackoverflow.com/questions/43895485/required-query-string-parameter-in-asp-net-core?