c# - NSwag:从一个 API 的多个版本生成 C# 客户端

Question

我们正在对我们的 API 进行版本控制，并使用 ASP.NET Core 1.1 中的 Swashbuckle 生成 Swagger 规范。我们可以根据这些 JSON 规范文件生成两个 API 文档:

<!-- language: c# -->
services.AddSwaggerGen(setupAction =>
{
    setupAction.SwaggerDoc("0.1", new Info { Title = "Api", Version = "0.1", Description = "API v0.1" });
    setupAction.SwaggerDoc("0.2", new Info { Title = "Api", Version = "0.2", Description = "API v0.2" });

    // more configuration omitted
}

我们将所有操作都包含在两个规范文件中，除非使用 [MapToApiVersion] 将其映射到特定版本和 ApiExplorerSettings(GroupName ="<version>")]属性。仅属于旧版本的方法也用 [Obsolete] 修饰属性:

<!-- language: c# -->
[MapToApiVersion("0.1")]
[ApiExplorerSettings(GroupName = "0.1")]
[Obsolete]

但是，我们只想从两个规范文件的联合生成一个 C# 客户端，其中所有方法都包含在客户端中，0.1 和 0.2，但所有过时的方法实际上都标记为过时。

我研究了 NSwag(我们现在已经使用了很长一段时间)和 AutoRest。 AutoRest 似乎support a merging scenario ，但由于模式验证错误，我无法让它工作(而且我非常不确定我们的特定场景是否会得到实际支持)。

到目前为止，我最后一个想法是将规范以某种方式 JSON 合并为一个规范，然后将其提供给 NSwag。

我们在这里遗漏了什么吗？这是否有可能通过 NSwag 实现？

Answer 1

我写了一篇关于类似问题的文章https://medium.com/dev-genius/nswag-charp-client-from-multiple-api-versions-7c79a3de4622

首先，创建一个架构。如我所见，有两种方法:

• 存在多个版本的模式
• 每个版本都有自己的架构

接下来，为每个受支持的版本创建客户端并将它们包装在包装器客户端下:

public class AppApiClient
{
    public IV1Client V1 { get; }
    public IV2Client V2 { get; }

    public AppApiClient(HttpClient httpClient)
    {
        V1 = new V1Client(httpClient);
        V2 = new V2Client(httpClient);
    }
}