Чем заменить Swagger в .NET WebAPI

// Установка NSwag из NuGet
dotnet add package NSwag.AspNetCore
 
// Базовая настройка в Program.cs
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApiDocument(); // Это заменяет AddSwaggerGen()
 
// Конфигурация в цепочке middleware
app.UseOpenApi(); // Генерирует JSON-спецификацию
app.UseSwaggerUi3(); // Добавляет Swagger UI

services.AddOpenApiDocument(options => {
    options.DocumentName = "v1";
    options.Title = "MyAwesomeAPI";
    options.Version = "1.0";
    options.Description = "API для управления чем-то очень важным";
    
    // Группировка по контроллерам
    options.DocumentProcessors.Add(new TagByControllerNameProcessor());
    
    // Кастомные схемы безопасности
    options.AddSecurity("JWT", new OpenApiSecurityScheme {
        Type = OpenApiSecuritySchemeType.ApiKey,
        Name = "Authorization",
        In = OpenApiSecurityApiKeyLocation.Header,
        Description = "Введите JWT токен: Bearer {token}"
    });
});

options.SchemaSettings.SchemaProcessors.Add(
    new NSwag.Generation.Processors.SchemaProcessor(
        (schema, type) =>
        {
            if (type == typeof(MyComplexType))
            {
                // Модифицируем схему для сложного типа
                schema.Properties["sensitiveInfo"] = null;
            }
        }
    )
);

options.OperationProcessors.Add(
    new OperationSecurityProcessor(
        (operation, context) =>
        {
            // Например, скрываем админский функционал в публичной документации
            if (operation.Tags.Contains("AdminOnly") && !context.IsAdminView)
            {
                return false; // Операция будет скрыта
            }
 
            return true;
        }
    )
);

services.AddOpenApiDocument(config => {
    config.DocumentName = "v1";
    config.ApiGroupNames = new[] { "v1" };
    // Настройки для v1
});
 
services.AddOpenApiDocument(config => {
    config.DocumentName = "v2";
    config.ApiGroupNames = new[] { "v2" };
    // Настройки для v2
});

services.AddOpenApiDocument(config => {
    config.GenerateControllers = true;  // Генерировать контроллеры
    config.GenerateTypescript = true;   // Включить генерацию TypeScript
    config.TypeScriptGeneratorSettings.TypeScriptVersion = 4.3;
    config.TypeScriptGeneratorSettings.Template = TypeScriptTemplate.Fetch;
    config.TypeScriptGeneratorSettings.DateTimeType = TypeScriptDateTimeType.String;
    config.TypeScriptGeneratorSettings.OutputPath = "ClientApp/src/api-client.ts";
});

options.CSharpGeneratorSettings.Namespace = "MyCompany.ApiClient";
options.CSharpGeneratorSettings.GenerateClientInterfaces = true;
options.CSharpGeneratorSettings.GenerateDtoTypes = true;
options.CSharpGeneratorSettings.ClientClassAccessModifier = "public";
options.CSharpGeneratorSettings.UseHttpClientCreationMethod = true;

// Для Angular проектов
config.TypeScriptGeneratorSettings.Template = TypeScriptTemplate.Angular;
config.TypeScriptGeneratorSettings.InjectionTokenType = InjectionTokenType.InjectionToken;
config.TypeScriptGeneratorSettings.AngularVersion = 13;
 
// Для обычного TypeScript с Axios
config.TypeScriptGeneratorSettings.Template = TypeScriptTemplate.Axios;

// Использование доп. генератора для Dart
services.AddOpenApiDocument()
    .AddCustomProcessor(new DartClientGeneratorProcessor("MyApi", "./lib/api_client.dart"));

app.UseSwaggerUi3(options =>
{
    options.CustomStylesheets.Add("./custom-styles.css");
    options.CustomJavaScripts.Add("./branding.js");
    options.DocExpansion = "list"; // Варианты: none, list, full
    options.DefaultModelsExpandDepth = 1;
    options.TagsSorter = "alpha"; // Сортировка тегов/групп
});

options.CustomDocumentTitle = "API Документация ФинтехСтарт";
options.CustomHeadContent = 
    "<meta name=\"description\" content=\"Интерактивная документация API\">";
options.CustomHtmlTemplate = File.ReadAllText("./SwaggerTemplate.html");

app.UseSwaggerUi3(options =>
{
    var host = context.Request.Host.Host;
    if (host.Contains("client-a"))
    {
        options.CustomStylesheets.Add("./client-a-style.css");
        options.CustomLogo = "client-a-logo.png";
    }
    else if (host.Contains("client-b"))
    {
        options.CustomStylesheets.Add("./client-b-style.css");
        options.CustomLogo = "client-b-logo.png";
    }
});

// Создаём тесты на основе OpenAPI спецификации
var document = await OpenApiDocument.FromUrlAsync("https://api.example.com/swagger/v1/swagger.json");
var apiTester = new ApiTester(document);
 
// Автоматически генерируем и выполняем тесты для всех GET-эндпоинтов
var results = await apiTester.TestGetEndpointsAsync(new ApiTestSettings {
    BaseUrl = "https://api.example.com",
    ExpectedStatusCode = 200,
    AuthToken = "your-auth-token-here"
});

var fixture = new Fixture();
fixture.Customize(new AutoNSubstituteCustomization());
 
// Генерируем тестовые данные на основе схемы из OpenAPI
var testData = fixture.Create<CreateUserRequest>();
testData.Email = "test@example.com"; // Переопределяем при необходимости
 
// Выполняем тест POST эндпоинта с сгенерированными данными
var result = await apiTester.TestPostEndpointAsync("/api/users", testData);

// Тестирование с разными ролями пользователей
foreach (var role in new[] { "user", "admin", "manager" })
{
    var token = authService.GetTokenForRole(role);
    var roleResults = await apiTester.TestAllEndpointsAsync(
        new ApiTestSettings { AuthToken = token });
        
    // Проверяем, что эндпоинты доступны согласно ролям
    Assert.True(roleResults
        .Where(r => r.Path.Contains("/admin/"))
        .All(r => role == "admin" ? r.IsSuccessful : r.StatusCode == 403));
}

services.AddOpenApiDocument(options => {
    // Базовая аутентификация
    options.AddSecurity("basic", new OpenApiSecurityScheme {
        Type = OpenApiSecuritySchemeType.Basic,
        Description = "Basic auth"
    });
    
    // API ключ
    options.AddSecurity("apiKey", new OpenApiSecurityScheme {
        Type = OpenApiSecuritySchemeType.ApiKey,
        Name = "X-API-Key",
        In = OpenApiSecurityApiKeyLocation.Header,
        Description = "API ключ для доступа к защищеным эндпоинтам"
    });
    
    // JWT токен
    options.AddSecurity("jwt", new OpenApiSecurityScheme {
        Type = OpenApiSecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
        Description = "JWT Authorization header. Пример: 'Bearer {token}'"
    });
});

options.AddSecurity("oauth2", new OpenApiSecurityScheme {
    Type = OpenApiSecuritySchemeType.OAuth2,
    Flows = new OpenApiOAuthFlows {
        AuthorizationCode = new OpenApiOAuthFlow {
            AuthorizationUrl = new Uri("https://auth.example.com/connect/authorize"),
            TokenUrl = new Uri("https://auth.example.com/connect/token"),
            Scopes = new Dictionary<string, string> {
                { "api:read", "Чтение данных" },
                { "api:write", "Запись данных" }
            }
        }
    }
});

options.OperationProcessors.Add(new OperationSecurityProcessor("jwt"));
 
// Или избирательно для конкретных операций
options.OperationProcessors.Add(new OperationSecuritySelectorProcessor(
    (operation, context) => {
        // Применяем JWT только к операциям с тегом "secured"
        if (operation.Tags.Contains("secured")) {
            operation.Security.Add(new OpenApiSecurityRequirement {
                { new OpenApiSecurityScheme { Reference = new OpenApiReference {
                    Id = "jwt", Type = ReferenceType.SecurityScheme } }, new string[] { } }
            });
        }
        return true;
    }
));

options.OperationProcessors.Add(new AspNetCoreOperationSecurityProcessor(
    provider => 
    {
        var policyProvider = provider.GetRequiredService<IAuthorizationPolicyProvider>();
        return policyProvider;
    }
));

// Разная документация для разных ролей
app.UseSwaggerUi3(settings => {
    if (User.IsInRole("Developer")) {
        settings.OAuth2Client = new OAuth2ClientSettings {
            ClientId = "dev-client",
            AppName = "Developer Portal",
            UsePkceWithAuthorizationCodeGrant = true
        };
    } else {
        settings.OAuth2Client = new OAuth2ClientSettings {
            ClientId = "external-client",
            AppName = "API Portal" 
        };
    }
});

// Устанавливаем пакет
dotnet add package Redoc.AspNetCore
 
// Регистрируем в Program.cs
builder.Services.AddOpenApi(); // Стандартная генерация OpenAPI для .NET 9
 
// Добавляем ReDoc UI
app.UseReDoc(options =>
{
    options.SpecUrl = "/openapi/v1.json"; // Путь к OpenAPI спецификации
    options.RoutePrefix = "docs"; // ReDoc будет доступен по адресу /docs
    options.DocumentTitle = "API Reference";
});

app.UseReDoc(options =>
{
    options.SpecUrl = "/swagger/v1/swagger.json";
    options.RoutePrefix = "api-docs";
    options.HideDownloadButton = true; // Скрываем кнопку скачивания JSON
    options.HideHostname = false; // Показываем имя хоста
});

/// <summary>
/// Получает список транзакций для указанного аккаунта.
/// 
/// ## Примечания
/// 
/// * Транзакции возвращаются в обратном хронологическом порядке
/// * Поддерживается пагинация через параметры [INLINE]page[/INLINE] и [INLINE]pageSize[/INLINE]
/// 
/// ![Диаграмма статусов](/images/transaction-states.png)
/// </summary>
[HttpGet("accounts/{accountId}/transactions")]
public async Task<ActionResult<PaginatedResult<Transaction>>> GetTransactions(
    [Description("ID аккаунта")] string accountId)
{
    // ...
}

app.UseReDoc(options =>
{
    options.SpecUrl = "/openapi/v1.json";
    options.Theme.Colors.Primary = "#32329f"; // Основной цвет
    options.Theme.Typography.FontFamily = "Roboto, sans-serif";
    options.Theme.Typography.HeadingsFont = "Montserrat, sans-serif";
    options.Theme.Logo.Gutter = "20px"; // Отступ для логотипа
});

app.UseReDoc(options =>
{
    options.SpecUrl = "/openapi/v1.json";
    options.RoutePrefix = "api-docs";
    
    // Использование внешнего CDN для скриптов ReDoc
    options.UseReDocProSettings = true; // Включаем Pro-версию (если есть лицензия)
    options.ConfigureReDoc = reDoc =>
    {
        reDoc.HideHostname = false;
        reDoc.PathInMiddlePanel = true;
        reDoc.RequiredPropsFirst = true;
        reDoc.SortPropsAlphabetically = true;
    };
    
    // Полный контроль через HTML
    options.IndexStream = () => 
      new FileStream("./ReDocIndex.html", FileMode.Open);
});

// В OpenAPI спецификации
options.AddDocumentProcessor(document =>
{
    document.Tags = new List<OpenApiTag>
    {
        new OpenApiTag { Name = "Accounts", Description = "Операции с аккаунтами" },
        new OpenApiTag { Name = "Transactions", Description = "Платежи и переводы" },
        new OpenApiTag 
        { 
            Name = "Reports", 
            Description = "Отчеты и аналитика",
            // Группировка тегов в ReDoc
            "x-displayName": "Аналитический блок"
        }
    };
});

app.UseReDoc(options =>
{
    options.SpecUrl = "/openapi/v1.json";
    options.Theme.SideBar.Width = "300px";
    options.Theme.SideBar.BackgroundColor = "#fafafa";
    options.Theme.SideBar.TextColor = "#333333";
    
    // Закрепить сайдбар при скроллинге
    options.UseFixedSidebar = true;
});

// Настройка отображения OAuth2 в ReDoc
options.OAuth2RedirectUrl = "https://api.example.com/oauth2-redirect.html";
options.OAuth2Callback = "function onOAuthComplete(token) { console.log('Got token:', token); }";

// В контроллере или обработчике минимального API
/// <summary>
/// Создает нового пользователя
/// </summary>
/// <remarks>
/// Sample request:
/// 
///     POST /api/users
///     {
///        "username": "johndoe",
///        "email": "john@example.com",
///        "firstName": "John",
///        "lastName": "Doe"
///     }
///     
/// </remarks>
[HttpPost]
[Produces("application/json")]
[ProducesResponseType(typeof(UserResponse), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> CreateUser([FromBody] CreateUserRequest request)
{
    // ...
}

app.UseReDoc(options =>
{
    options.SpecUrl = "/openapi/v1.json";
    options.RoutePrefix = "docs";
    
    // Включаем интерактивные запросы
    options.EnableTryItOut = true;
    options.TryItOutConfig = new TryItOutConfig
    {
        // Настройки для Try-It-Out
        EnableRequestPayloadValidation = true,
        EnableResponseValidation = true,
        DefaultExpandResponses = "200,201", // Автоматически раскрываем успешные ответы
    };
});

// Добавляем экспорт запросов в различные форматы
options.EnableRequestExamples = true;
options.RequestExamplesConfig = new RequestExamplesConfig
{
    AvailableFormats = new[] { "curl", "postman", "httpie" },
    DefaultFormat = "curl"
};

// Добавляем несколько примеров к операции
options.AddDocumentProcessor(document =>
{
    var createUserOperation = document.Paths["/api/users"]
        .Operations[OpenApiOperationType.Post];
        
    createUserOperation.RequestBody.Content["application/json"].Examples 
        = new Dictionary<string, OpenApiExample>
    {
        ["basic"] = new OpenApiExample
        {
            Summary = "Базовый пример",
            Value = new { username = "user1", email = "user@example.com" }
        },
        ["complete"] = new OpenApiExample
        {
            Summary = "Полный пример",
            Value = new { 
                username = "johndoe", 
                email = "john@example.com",
                firstName = "John",
                lastName = "Doe",
                settings = new {
                    theme = "dark",
                    notifications = true
                }
            }
        }
    };
});

// Генератор примеров на основе схем
services.AddTransient<IOpenApiExampleGenerator, SmartExampleGenerator>();
services.AddOpenApiDocument(options =>
{
    options.UseExamplesFromAttributes = true;
    options.GenerateExamples = true;
    options.ExampleGenerator = new SmartExampleGenerator();
});

// Примеры на разных языках
createUserOperation.Responses["200"].Content["application/json"].Examples 
    = new Dictionary<string, OpenApiExample>
{
    ["en"] = new OpenApiExample
    {
        Summary = "English response",
        Value = new { message = "User created successfully" }
    },
    ["ru"] = new OpenApiExample
    {
        Summary = "Ответ на русском",
        Value = new { message = "Пользователь успешно создан" }
    }
};

options.AddDocumentProcessor(document =>
{
    var paymentTag = document.Tags.FirstOrDefault(t => t.Name == "Payments");
    if (paymentTag != null)
    {
        paymentTag.Description = @"
[H2]Платежный модуль API[/H2]
 
Платежный модуль позволяет:
* Создавать транзакции
* Подтверждать платежи
* Отменять транзакции
* Получать отчеты
 
### Процесс обработки платежа
1. Создание платежа
2. Авторизация
3. Подтверждение
4. Завершение
 
| Статус | Описание | Возможные действия |
|--------|----------|------------------|
| Pending | Ожидание | Confirm, Cancel |
| Confirmed | Подтвержден | Refund |
| Cancelled | Отменен | - |
";
    }
});

/// <summary>
/// Получает историю транзакций
/// </summary>
/// <remarks>
/// Получает полную историю транзакций по аккаунту.
/// 
/// <div class="warning">
///   <strong>Внимание!</strong> Этот метод может возвращать большие объемы данных. 
///   Используйте параметры пагинации.
/// </div>
/// 
/// <style>
/// .warning {
///   background-color: #fff8e6;
///   border-left: 4px solid #f0ad4e;
///   padding: 12px;
///   margin-bottom: 16px;
/// }
/// </style>
/// </remarks>
[HttpGet("transactions/history")]
public async Task<ActionResult<List<Transaction>>> GetTransactionHistory(
    [FromQuery] int page = 1,
    [FromQuery] int pageSize = 20)
{
    // реализация
}

app.UseReDoc(options =>
{
    options.IndexStream = () => new FileStream(
        Path.Combine(AppContext.BaseDirectory, "ReDocTemplate.html"), 
        FileMode.Open);
});

// Регистрируем несколько версий OpenAPI
app.MapOpenApi("v1", options => /* настройки V1 */);
app.MapOpenApi("v2", options => /* настройки V2 */);
 
// ReDoc с выбором версий
app.UseReDoc(options =>
{
    options.DocumentTitle = "API Reference";
    options.SpecUrl = new Dictionary<string, string>
    {
        ["v1"] = "/openapi/v1.json",
        ["v2"] = "/openapi/v2.json"
    };
});

options.EnableSearch = true;
options.SearchConfig = new SearchConfig
{
    FullTextSearch = true,
    MinSearchChars = 3,
    HighlightResults = true
};

// Устанавливаем нужный пакет
dotnet add package Swashbuckle.AspNetCore.Filters
 
// Добавляем поддержку примеров в Program.cs
builder.Services.AddOpenApi()
    .AddSwaggerExamplesFromAssemblyOf<Program>();

public class CreateOrderRequestExample : IExamplesProvider<CreateOrderRequest>
{
    public CreateOrderRequest GetExamples()
    {
        return new CreateOrderRequest
        {
            CustomerId = "CUST-12345",
            Items = new List<OrderItem>
            {
                new() { ProductId = "PROD-001", Quantity = 2, UnitPrice = 19.99m },
                new() { ProductId = "PROD-015", Quantity = 1, UnitPrice = 39.50m }
            },
            ShippingAddress = new Address
            {
                Street = "123 Main St",
                City = "New York",
                ZipCode = "10001",
                Country = "USA"
            },
            PaymentMethod = PaymentMethod.CreditCard
        };
    }
}

[HttpPost("orders")]
[SwaggerRequestExample(typeof(CreateOrderRequest), typeof(CreateOrderRequestExample))]
[ProducesResponseType(typeof(OrderCreatedResponse), StatusCodes.Status201Created)]
public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
{
    // Реализация
}

// В OpenAPI-спецификации можем добавить сразу несколько примеров
document.Paths["/api/payments"]
    .Operations[OpenApiOperationType.Post]
    .RequestBody.Content["application/json"].Examples = new Dictionary<string, OpenApiExample>
{
    ["simple-purchase"] = new OpenApiExample
    {
        Summary = "Простая покупка",
        Value = new { amount = 9.99, currency = "USD", paymentMethod = "card" }
    },
    ["subscription"] = new OpenApiExample
    {
        Summary = "Подписка",
        Value = new { amount = 15.99, currency = "EUR", paymentMethod = "card", recurring = true, period = "monthly" }
    }
};

public class DynamicExampleProvider : IRequestExampleProvider
{
    private readonly ITestDatabaseService _testDb;
    
    public DynamicExampleProvider(ITestDatabaseService testDb)
    {
        _testDb = testDb;
    }
    
    public async Task<object> GetExampleAsync(Type requestType, string operationId)
    {
        if (operationId == "CreateOrder")
        {
            // Получаем последний реальный заказ из тестовой базы
            var lastOrder = await _testDb.GetLastOrderAsync();
            return new CreateOrderRequest
            {
                // Преобразуем в формат запроса
                // ...
            };
        }
        
        return null; // Для других операций используем стандартные примеры
    }
}

app.UseReDoc(options =>
{
  options.SpecUrl = new Dictionary<string, string>
  {
      ["v1"] = "/openapi/v1.json",
      ["v2"] = "/openapi/v2.json",
      ["v3-beta"] = "/openapi/v3-beta.json"
  };
  options.RoutePrefix = "docs";
  options.DocumentTitle = "API Reference";
});

options.ConfigureRedoc(redoc =>
{
  redoc.VersionSwitcher = true;
  redoc.VersionColors = new Dictionary<string, string>
  {
      ["v1"] = "#9e9e9e", // Серый для устаревшей версии
      ["v2"] = "#4caf50", // Зелёный для текущей стабильной версии
      ["v3-beta"] = "#ff9800" // Оранжевый для бета-версии
  };
});

options.AddOperationFilter<DeprecatedOperationFilter>();
 
// Фильтр, который помечает устаревшие эндпоинты
public class DeprecatedOperationFilter : IOperationFilter
{
  public void Apply(OpenApiOperation operation, OperationFilterContext context)
  {
      var apiVersion = context.ApiDescription.ActionDescriptor.EndpointMetadata
          .OfType<ApiVersionAttribute>()
          .FirstOrDefault();
          
      if (apiVersion?.Deprecated == true)
      {
          operation.Deprecated = true;
          operation.Description = $" [B]Устарело с версии {apiVersion.Version}[/B]\n\n{operation.Description}";
      }
  }
}

// Пример полиморфной модели с использованием oneOf
document.Components.Schemas["PaymentMethod"] = new OpenApiSchema
{
    OneOf = new List<OpenApiSchema>
    {
        new OpenApiSchema { Reference = new OpenApiReference { 
            Id = "CreditCardPayment", Type = ReferenceType.Schema } },
        new OpenApiSchema { Reference = new OpenApiReference { 
            Id = "BankTransferPayment", Type = ReferenceType.Schema } }
    },
    Description = "Способ оплаты, который может быть либо кредитной картой, либо банковским переводом"
};

options.SchemaSettings.MaxRecursiveDepth = 2; // Показывать рекурсию только на 2 уровня

// Пример базовой модели с дискриминатором
document.Components.Schemas["Vehicle"] = new OpenApiSchema
{
    Properties = new Dictionary<string, OpenApiSchema>
    {
        ["type"] = new OpenApiSchema { Type = "string", Description = "Тип транспортного средства" }
    },
    Discriminator = new OpenApiDiscriminator
    {
        PropertyName = "type",
        Mapping = new Dictionary<string, string>
        {
            ["car"] = "#/components/schemas/Car",
            ["motorcycle"] = "#/components/schemas/Motorcycle"
        }
    }
};

// Подключение Stoplight-сгенерированной спецификации к ASP.NET Core
app.UseOpenApi(options => {
    options.DocumentName = "v1";
    options.Path = "/api-docs/v1.json";
    options.SerializeAsV2 = false; // Используем OpenAPI 3.0
});
 
// Использование документации из Stoplight в ASP.NET Core проекте
app.UseReDoc(options => {
    options.SpecUrl = "/stoplight-spec.json";
    options.RoutePrefix = "docs";
    options.DocumentTitle = "API Docs";
    // Можно подключить стили из Stoplight
    options.Theme.Fonts.MonoFont = "Roboto Mono, monospace";
});

// Пример кода для экспорта OpenAPI из .NET сервиса
public static async Task ExportOpenApiToStoplight(string apiKey, string projectId)
{
    var openApiJson = await GenerateOpenApiDocument();
    
    using var client = new HttpClient();
    client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
    
    var content = new StringContent(
        openApiJson, 
        Encoding.UTF8, 
        "application/json");
    
    var response = await client.PostAsync(
        $"https://api.stoplight.io/v1/projects/{projectId}/versions", 
        content);
    
    response.EnsureSuccessStatusCode();
}

// Сравнительная оценка по 5-балльной шкале
                      | NSwag | ReDoc | Stoplight
----------------------|-------|-------|----------
Простота внедрения    |   4   |   5   |    2
Документирование      |   4   |   5   |    5
Генерация клиентов    |   5   |   1   |    4
Коллаборация         |   2   |   1   |    5
Визуальный дизайн     |   3   |   4   |    5
Интеграция с CI/CD    |   4   |   3   |    5

// Параллельный запуск Swagger и ReDoc
if (app.Environment.IsDevelopment())
{
    // Старый Swagger UI
    app.UseSwagger();
    app.UseSwaggerUI();
    
    // Новый ReDoc, размещенный на другом маршруте
    app.UseReDoc(options =>
    {
        options.SpecUrl = "/swagger/v1/swagger.json"; // Используем тот же JSON
        options.RoutePrefix = "api-docs";
    });
}

// Было в Swagger
[SwaggerSubType(typeof(CreditCardPayment))]
[SwaggerSubType(typeof(PayPalPayment))]
public abstract class PaymentMethod { /* ... */ }
 
// Стало в NSwag
[JsonConverter(typeof(JsonInheritanceConverter), "discriminator")]
[KnownType(typeof(CreditCardPayment))]
[KnownType(typeof(PayPalPayment))]
public abstract class PaymentMethod { /* ... */ }