使用Swagger，ApiExplorer和NSwag掌握ASP.NET Core和ABP中的外部Web API

services.AddSwaggerGen(options =>
{
    // add two swagger files, one for the web app and one for clients
    options.SwaggerDoc("v1", new OpenApiInfo() 
    { 
        Title = "LeesStore API", 
        Version = "v1" 
    });
    options.SwaggerDoc("client-v1", new OpenApiInfo 
    { 
        Title = "LeesStore Client API", 
        Version = "client-v1" 
    });

从技术上讲，这是说我有两个版本的同一API，而不是两个单独的API，但是效果是相同的。第一个swagger文件在:http://localhost/swagger/v1/swagger.json公开，第二个在http://localhost/swagger/client-v1/swagger.json公开。

app.UseSwaggerUI(options =>
{
    var baseUrl = _appConfiguration["App:ServerRootAddress"]
        .EnsureEndsWith('/');
    options.SwaggerEndpoint(
        $"{baseUrl}swagger/v1/swagger.json", 
        "LeesStore API V1");
    options.SwaggerEndpoint(
        $"{baseUrl}swagger/client-v1/swagger.json", 
        "LeesStore Client API V1");

现在，我可以在右上方的“选择定义”下拉列表中的两个swagger文件之间进行选择：

public class SwaggerFileMapperConvention : IControllerModelConvention
{
    public void Apply(ControllerModel controller)
    {
        var controllerNamespace = controller?.ControllerType?.Namespace;
        if (controllerNamespace == null) return;
        var namespaceElements = controllerNamespace.Split('.');
        var nextToLastNamespace = namespaceElements.ElementAtOrDefault
                                  (namespaceElements.Length - 2)?.ToLowerInvariant();
        var isInClientNamespace = nextToLastNamespace == "client";
        controller.ApiExplorer.GroupName = isInClientNamespace ? "client-v1" : "v1";
    }
}

如果运行该命令，则会看到所有内容仍然重复。这是因为Startup.cs中这行：

services.AddSwaggerGen(options =>{
    options.DocInclusionPredicate((docName, description) => true);

当发生冲突时，DocInclusionPredicate获胜。

#addin nuget:?package=Cake.CodeGen.NSwag&version=1.2.0&loaddependencies=true
…
Task("CreateProxy")
   .Description("Uses nswag to re-generate a c# proxy to the client api.")
   .Does(() =>
{
    var filePath = DownloadFile("http://localhost:21021/swagger/client-v1/swagger.json");

    Information("client swagger file downloaded to: " + filePath);
    var proxyClass = "ClientApiProxy";
    var proxyNamespace = "LeesStore.Cmd.ClientProxy";
    var destinationFile = File("./aspnet-core/src/LeesStore.Cmd/ClientProxy/ClientApiProxy.cs");
    
    var settings = new CSharpClientGeneratorSettings
    {
       ClassName = proxyClass,
       CSharpGeneratorSettings = 
       {
          Namespace = proxyNamespace
       }
    };

    NSwag.FromJsonSpecification(filePath)
        .GenerateCSharpClient(destinationFile, settings);

});

在Mac/linux 上运行build.ps1 -target CreateProxy或build.sh -target CreateProxy，然后弹出一个我可以在这样的控制台中使用的强类型ClientApiProxy类：

using var httpClient = new HttpClient();
var clientApiProxy = new ClientApiProxy("http://localhost:21021/", httpClient);
var product = await clientApiProxy.ProductAsync(productId);
Console.WriteLine($"Your product is: '{product.Name}'");

{"result":{"name":"The Product","quantity":0,"id":2},
"targetUrl":null,"success":true,"error":null,"unAuthorizedRequest":false,"__abp":true}

乍看之下，这似乎是合理的。但是，这不会反序列化为ProductDto，因为JSON中的ProductDto处于“result”对象内。包装功能是ABP如何（以及其他方式）在漂亮的模态对话框中将UserFriendlyException消息返回给用户。

{"result":null,"targetUrl":null,"success":false,
"error":{"code":0,"message":"Dude, an exception just occurred, 
maybe you should check on that","details":null,"validationErrors":null},
"unAuthorizedRequest":false,"__abp":true}

事实证明该解决方案非常简单。将DontWrapResult属性放到控制器上：

[DontWrapResult(WrapOnError = false, WrapOnSuccess = false, LogError = true)]
public class ProductController : LeesStoreControllerBase

结果是干净的JSON：

{"name":"The Product","quantity":0,"id":2}

和控制台应用程序一起编写Your product is "The Product"。

[HttpGet("api/client/v1/product/{id}")]
public async Task GetProduct(int id)

该ApiExplorer只露出了终点，而不是方法名。因此，Swashbuckle 在Swagger文件中不包含operationId，NSwag被迫使用端点中的元素来命名。

[HttpGet("api/client/v1/product/{id}", Name = nameof(GetProduct))]
public async Task GetProduct(int id)

这产生了await clientApiProxy.GetProductAsync(productId);我所期望的。