如何在.Net Core中生成OpenApi Client SDK项目

Question

我们的客户为我们提供了他们所有 API 端点的 swagger 链接。我们有一个使用 VS 2022 和 .Net 6 的 .Net Core 项目。现在我们想要为相同的 .Net Core 解决方案生成一个 OpenAPI 客户端项目，以便我们通过 OpenAPI 项目调用客户端的 API 端点。

我遵循的步骤是：

• 我从客户端下载了 swagger json 文件。
• 我遵循了这个文档

正如该文档中提到的，首先，我使用此命令安装了 Open API

npm install @openapitools/openapi-generator-cli -g

然后，当我执行 OpenAPI Generator CLI 使用此命令生成 SDK 时，我收到错误“Java”未被识别为内部或外部命令

openapi-generator generate -i swagger.json -g csharp-netcore -o Api.Client.Sdk --additional-properties packageName=Api.Client.Sdk

Answer 1

您可能应该从OpenAPI 上的 ASP.NET Core 文档开始，了解 OpenAPI 是什么以及各个库的作用。OpenAPI 不是库或自定义协议。这是指定 HTTP API 端点和 DTO 的常用方法。您不需要创建任何特殊的东西来调用 HTTP API，只需使用 HttpClient。生成器可用于从 OpenAPI 链接生成 DTO，但这不是必需的。

Swashbuckle 只是一个可用于创建提供 OpenAPI 架构的 Web API 项目的库。它通过swagger.json从应用程序的控制器和 DTO 生成文档来实现此目的。如果您愿意，您可以手动创建该文档，但 Swashbuckle 肯定更易于使用。

您可以使用 NSwag 等库从 OpenAPI 架构生成样板客户端代码。一种方法是通过dotnet api 工具，该工具从 Swagger 文档生成 C# 客户端和对象。

您可以使用以下命令安装该工具

dotnet tool install -g Microsoft.dotnet-openapi

并使用它dotnet openapi add url ....来配置您的项目以在构建时生成 C# 代码。

假设您使用以下命令创建一个空的控制台应用程序

dotnet new console

您可以添加基于https://petstore3.swagger.io/架构生成客户端

dotnet openapi add url https://petstore3.swagger.io/api/v3/openapi.json --help

这会将 NuGet 包添加NSwag.ApiDescription.Client到应用程序中，并添加一个OpenApiReference指向架构文档的标记。这样当模式改变时客户端可以刷新。

该csproj文件将如下所示：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="12.0.2" />
    <PackageReference Include="NSwag.ApiDescription.Client" Version="13.0.5" />
  </ItemGroup>
  <ItemGroup>
    <OpenApiReference Include="openapi.json" SourceUrl="https://petstore3.swagger.io/api/v3/openapi.json" />
  </ItemGroup>
</Project>

该工具还将在文件夹openapiClient内生成一个文件和类obj，这使其可供应用程序的其余部分使用。现在可以在 Program.cs 中使用客户端：

Console.WriteLine("Hello, World!");

var http = new HttpClient() { BaseAddress = new Uri("https://petstore3.swagger.io/") };

var client = new openapitest.openapiClient(http);
var results = await client.GetInventoryAsync();

Console.WriteLine(results);

该工具本身使用NSwag 库进行代码生成。还有其他工具和应用程序可以从 OpenAPI 文档生成 C# 代码。