ASP.NET 核心：NSwag 与 Swashbuckle

Posted 2023-03-31

【中文标题】ASP.NET 核心：NSwag 与 Swashbuckle

【英文标题】：ASP.NET core: NSwag vs. Swashbuckle

【发布时间】：2021-03-10 13:19:32

【问题描述】：

我们目前将 Swashbuckle.AspNetCore 用于 API 文档，但在生成客户端模型（Typescript）时，它似乎存在一个主要缺点。

作为示例，我使用基类增强了已知的 ASP.NET 默认项目 (WeatherForecast)

public class InfoEntryBase    
        
   public string Name  get; set; 
   public string Description  get; set; 


public class WeatherForecast : InfoEntryBase

   public DateTime Date  get; set; 

   public int TemperatureC  get; set; 

   public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

   public string Summary  get; set; 

然后它将 WeatherForecast 公开为

WeatherForecast
name    string
nullable: true
description string
nullable: true
date    string($date-time)
temperatureC    integer($int32)
temperatureF    integer($int32)
readOnly: true
summary string
nullable: true

并且继承丢失。 这将使得无法从服务器端代码自动生成客户端模型，因为我们自然喜欢将继承移植到 Typescript 代码。

在调查 NSwag.AspNetCore 时，我发现它可以处理继承问题。它暴露了：

WeatherForecast
name    string
description string
date*   string($date-time)
temperatureC*   integer($int32)
temperatureF*   integer($int32)
summary string

InfoEntryBase
name    string
description string

我是否忽略了有关 Swashbuckle 的某些内容，或者没有其他选择可以从它切换到 NSwag？

您可以查看代码 https://github.com/ClemensOesterle/NSwagSpike/tree/swashbuckle 而 NSwag 实现驻留在 master 分支中。

【参考方案1】：

这样就解决了。

services.AddSwaggerGen(options =>

    options.UseAllOfForInheritance();