13 сен 2023 в 23:59

Создание спецификации ASP.NET Core OpenAPI во время сборки

Ожидает приглашения

Генерация OpenAPI с помощью .NET CLI

Необходимо создать локальный манифест инструмента для того чтобы проект мог вызывать инструментарий CLI Swashbuckle из контекста нашего решения. Для этого мы сначала запустим команду .NET CLI

dotnet new tool-manifest

Команда dotnet new tool-manifestсоздаст файл .config/dotnet-tools.json. Это файл, содержащий список установленных инструментов и их версию.

{
  "version": 1,
  "isRoot": true,
  "tools": {}
}

Затем необходимо установить инструмент CLI Swashbuckle.

dotnet tool install SwashBuckle.AspNetCore.Cli

Команда dotnet tool install Swashbuckle.AspNetCore.Cliустановит интерфейс командной строки Swagger и добавит его в файл манифеста.

Если нужна конкретная версия, то необходимо использовать--version x.y.z.
Если добавлено несколько источников Nuget, установка может завершиться неудачей, поскольку установщик сначала будет искать неправильный источник. Необходимо добавить --ignore-failed-sourcesчтобы обойти это.

Так должен выглядеть файл манифеста с установленным инструментом:

  "tools": {
    "swashbuckle.aspnetcore.cli": {
      "version": "6.5.0",
      "commands": [
        "swagger"
      ]
    }
  }

Чтобы запустить инструмент генерации OpenAPI спецификации на этапе сборки необходимо изменить настройки проекта <projectname>.csproj, добавив в него новый <Target></Targer>

<Target Name="Generate OpenAPI" AfterTargets="Build" Condition="$(Configuration)=='Debug'">
    <Exec Command="dotnet tool restore"></Exec>
    <Exec Command="del ..\..\api\ /q /s"></Exec>
    <Exec Command="dotnet swagger tofile --output ..\..\api\openapi.yaml --yaml $(OutputPath)$(AssemblyName).dll v1" WorkingDirectory="$(ProjectDir)"></Exec>
    <Exec Command="dotnet swagger tofile --output ..\..\api\openapi.json $(OutputPath)$(AssemblyName).dll v1" WorkingDirectory="$(ProjectDir)"></Exec>
</Target>

Поскольку файл манифеста отслеживает инструменты, команда dotnet tool restore их легко восстановить на новом компьютере

А также необходимо почистить каталог, командой del ....\api\ /q /s где находятся файлы спецификации.

И запустить генерацию новых файлов спецификации в yaml и json формате.

Использование статической спецификации OpenAPI

if (app.Environment.IsDevelopment())
{
    app.UseStaticFiles(new StaticFileOptions()
    {
        FileProvider = new PhysicalFileProvider(Path.GetFullPath(@"../../api/")),
        RequestPath = new PathString("/api")
    });

    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/api/openapi.json", "OpenAPI");
    });
}

Преимущества статических спецификаций OpenAPI

Передавать эти файлы из CDN, снижая нагрузку на наш сервер.
Передавать спецификации OpenAPI третьим лицам.
Использовать спецификации OpenAPI с различными инструментами (например, JetBrains Rider).
Отсутствие необходимости отслеживания изменений в коде контроллера или его методов.
Отсутствие необходимости создания спецификации во время выполнения сокращает время запуска приложения.

Источники

Теги:

Хабы: