Reo.Core.ApiDocumentation

---

Описание пакета

Пакет Reo.Core.ApiDocumentation предназначен для интеграции Swagger (OpenAPI) с IdentityServer в ASP.NET Core-приложениях. Он решает проблему автоматической настройки Swagger-документации с поддержкой OAuth2-авторизации, используя конфигурации клиентов из IdentityServer.

Основные функции:

• Автоматическое получение информации о клиенте (ClientId, AllowedScopes) из IdentityServer.
• Настройка Swagger-документации с поддержкой OAuth2.
• Поддержка кастомных фильтров и операций для Swagger.

---

Основные компоненты

1. ClientDefinition

• Описание: Класс, содержащий метаданные о клиенте (ClientId, ClientName, AllowedScopes, TokenEndpoint и т.д.).
• Использование: Используется для передачи информации о клиенте в Swagger-конфигурацию.

2. IdentityClientSwaggerDefinitionStrategy

• Описание: Стратегия для получения определения клиента из IdentityServer через API-запрос.
• Использование: Используется для динамической загрузки конфигурации клиента из IdentityServer.

3. DefaultConfigureSwaggerOptions

• Описание: Класс для настройки SwaggerGen с использованием информации о клиенте.
• Использование: Регистрируется как IConfigureOptions<SwaggerGenOptions> для автоматической настройки Swagger.

4. DefaultPathDocumentFilter

• Описание: Фильтр для документа Swagger, удаляющий серверы по умолчанию.
• Использование: Применяется для кастомизации вывода Swagger-документации.

---

Требования

• .NET: .NET Core 3.1, .NET 5+, .NET 6+.
• Зависимости:
  • Swashbuckle.AspNetCore (для генерации Swagger).
  • IdentityModel.Client (для работы с IdentityServer).

---

Установка

NuGet Package Manager

Install-Package Reo.Core.ApiDocumentation -Version 1.0.0

.NET CLI

dotnet add package Reo.Core.ApiDocumentation --version 1.0.0

---

Настройка

Регистрация в ASP.NET Core

Добавьте в Startup.cs или Program.cs (для .NET 6+):

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        options.UseDefaultConfiguration();
    });

    services.Configure<AuthConfigureOptions>(Configuration.GetSection("Auth"));
}

Конфигурационные параметры

Добавьте в appsettings.json:

{
  "Auth": {
    "IdentityServerUrl": "https://identityserver.example.com",
    "ClientId": "my-client-id"
  }
}

---

Использование

Пример 1: Настройка Swagger с OAuth2

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        c.UseDefaultConfiguration(); // Использует конфигурацию из IdentityServer
        c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
        {
            Type = SecuritySchemeType.OAuth2,
            Flows = new OpenApiOAuthFlows
            {
                Implicit = new OpenApiOAuthFlow
                {
                    AuthorizationUrl = new Uri("https://identityserver.example.com/connect/authorize"),
                    TokenUrl = new Uri("https://identityserver.example.com/connect/token")
                }
            }
        });
    });
}

Пример 2: Кастомизация Swagger UI

app.UseSwaggerUI(options =>
{
    options.OAuthClientId("my-client-id");
    options.OAuthClientSecret("my-client-secret");
    options.OAuthAppName("My Application");
});

---

Лицензия

Этот пакет распространяется под лицензией MIT License. См. файл LICENSE для подробностей.

---

Репозиторий и поддержка

• **Репозиторий: ** https://github.com/your-repo/Reo.Core.ApiDocumentation
• Сообщить об ошибках: Откройте issue на GitHub.
• Запросить помощь: Напишите на support@example.com.

---

Контакты

• Автор: Иван Петров
• Email: ivan.petrov@example.com
• Twitter: @ivanpetrov_dev
• LinkedIn: https://linkedin.com/in/ivanpetrov

---

📌 Пакет активно развивается. Для получения обновлений подписывайтесь на репозиторий.