Ровно год назад писал пост про синхронизацию через OpenAPI.
Тот подход был основан на Swagger. С тех пор в .NET появился встроенный функционал для генерации спецификаций OpenAPI. Держите короткий гайд:
1. Создаём новый проект:
mkdir -p backend
cd backend
dotnet new webapi
По умолчанию файл проекта backend.csproj уже использует нужный пакет Microsoft.AspNetCore.OpenApi.
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.7" />
Можно запустить приложение и перейти по адресу https://localhost:{port}/openapi/v1.json, чтобы убедиться, что всё работает.
2. Следующий шаг – автоматическая генерация спецификации в виде файла.
Для этого нужно установить ещё один пакет:
dotnet add package Microsoft.Extensions.ApiDescription.Server
И включить генерацию при сборке, добавив в backend.csproj вот этот блок:
<PropertyGroup">
<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
<OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
<OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
</PropertyGroup>
Теперь, если выполнить команду dotnet build, файл спецификации автоматически создастся в директории с проектом. В нашем случае – это файл backend.json.
3. Дальнейшие шаги, связанные с фронтом, остались без изменений – используем пакет swagger-typescript-api:
pnpx swagger-typescript-api generate --path ./backend.json -o ./generated -n WebApi.ts
Сгенерированные типы TypeScript будут лежать в ./generated/WebApi.ts.