День 1884. #ЗаметкиНаПолях
Генерация Спецификации OpenAPI при Сборке Проекта ASP.NET
Спецификация OpenAPI — мощный инструмент для описания и документирования API. Это стандарт, который позволяет вам определить структуру вашего API, включая конечные точки, модели запросов и ответов, а также требования безопасности. Спецификация OpenAPI — это файл JSON или YAML, который можно использовать для создания документации, клиентских библиотек и серверных заглушек.

Большинство разработчиков .NET генерируют спецификацию из кода. Библиотека Swashbuckle.AspNetCore — популярный выбор для создания спецификации OpenAPI на основе проектов веб-API ASP.NET Core. Вы можете легко добавить страницу для доступа к спецификации. Однако сложно проверить содержание спецификации, чтобы убедиться, что спецификация пригодна для использования потребителями. Один из способов улучшить это — сделать спецификацию частью вашего кода, чтобы вы могли просматривать ее во время проверок кода.

Microsoft предоставляет пакет NuGet Microsoft.Extensions.ApiDescription.Server, который позволяет генерировать спецификацию OpenAPI из кода во время сборки проекта.
Сначала создадим новый проект веб-API и добавим пакет Microsoft.Extensions.ApiDescription.Server:

dotnet new webapi --framework net8.0
dotnet add package Microsoft.Extensions.ApiDescription.Server

Теперь можно добавить следующие свойства в файл .csproj проекта, чтобы настроить генерацию спецификации OpenAPI:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>

    <OpenApiDocumentsDirectory>
     $(MSBuildProjectDirectory)
    </OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiGenerateDocumentsOnBuild>
     true
    </OpenApiGenerateDocumentsOnBuild>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.3" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="8.0.3">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>
</Project>

Теперь при сборке проекта спецификация будет сгенерирована в корне проекта в файле <ИмяПроекта>.json.

Источник: https://www.meziantou.net/generate-openapi-specification-at-build-time-from-the-code-in-asp-net-core.htm