Swagger — это инструмент с открытым исходным кодом для проектирования, создания и документирования веб-API. Он предоставляет набор стандартизированных спецификаций, которые позволяют разработчикам четко определять конечные точки API, параметры, запросы и ответы. С помощью Swagger пользователи могут создавать документы API в реальном времени с интерактивным пользовательским интерфейсом, что упрощает совместную работу команды и сторонних разработчиков для понимания и использования API. Он поддерживает несколько языков программирования и платформ и предоставляет богатые функции, такие как автоматическая генерация кода, образцы запросов и тестовые примеры. Цель Swagger — упростить процесс разработки API, улучшить качество документации и облегчить общение между разработчиками, тестировщиками и другими заинтересованными сторонами. Документация Swagger важна при разработке веб-API, что отражается в следующих аспектах:

1. читаемыйсекси理解секс： Документация Swagger предоставляет понятную и структурированную документацию по API.,включить разработчиков、тестери Легко понятен другим членам командыAPIизконечная точка、параметр、Структура запроса и ответа.
2. Работа в команде: проходитьSwaggerдокумент,Члены команды могут делитьсяисотрудничествосуществоватьAPIиздизайни В процессе разработки。документ作为统一из Ссылки,Помогает сохранить командуизпоследовательныйсексисовместная работа。
3. Генерация кода и тестирование: SwaggerСпецификация поддерживает автоматическую генерацию клиентского кода.и Код-заглушка на стороне сервера,Повышенная эффективность разработки. в то же время,на основеSwaggerдокументиз Инструменты тестирования могут автоматически генерировать тестовые примеры,убеждатьсяAPIиз正确секси稳定секс。
4. Сторонние интеграции: Swaggerдокумент为第三方开发者提供了подробныйизAPIинформация,Ограниченный доступииспользоватьAPIизтрудность。Это помогает продвигать экосистемуизразвивать,улучшатьAPIиз可用секси可扩展секс。
5. Контроль версий и эволюция: Swaggerдокумент记录了APIиз版本информация,Поддержка в процессе эволюциииз Плавная миграция。Разработчики могут четко понимать каждую версиюизизменять,Помогает с обновлениями и обслуживанием.

1. Интеграция Swagger в ASP.NET Core Web Api.

Интеграция Swagger в веб-API ASP.NET Core — это эффективный способ автоматического создания, отображения и тестирования документов API. Вот основные шаги по интеграции Swagger в веб-API ASP.NET Core:

Установить Сваггер NuGet-пакеты: Используйте диспетчер пакетов NuGet или инструмент командной строки, чтобы установить пакет Swashbuckle.AspNetCore в свой проект. Этот пакет обеспечивает реализацию и интеграцию Swagger в ASP.NET. Инструменты Core.

dotnet add package Swashbuckle.AspNetCore

Настройте службу Swagger: существоватьStartup.csдокументизConfigureServicesв методе,добавить вSwaggerСлужитьиз Конфигурация。

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
});

Добавьте промежуточное ПО Swagger: существоватьStartup.csдокументизConfigureв методе,Включить промежуточное программное обеспечение Swagger,и КонфигурацияUIизконечная точка。

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
});

Запустите приложение: Запустите приложение и получите доступ к Swagger. Пользовательский интерфейс. По умолчанию Сваггер UIиз Адрес/swagger.

dotnet run

Посетите Сваггер UI： Откройте браузер, Посетите Сваггер Адрес пользовательского интерфейса по умолчанию: http://localhost:5000/swagger. Если в конфигурации имеются пользовательские порты или пути, измените адрес доступа соответствующим образом.

Проверьте созданную документацию: В Сваггере В пользовательском интерфейсе вы можете просматривать конечные точки, параметры и ответы API и даже тестировать API в пользовательском интерфейсе.

Выполнив описанные выше шаги, вы успешно интегрировали Swagger в веб-API ASP.NET Core. Такая интеграция не только обеспечивает удобную документацию, но также предоставляет разработчикам и командам интерактивный инструмент тестирования API.

2. Аннотации веб-API

2.1 XML-комментарии

Комментарии XML — это стандартизированный способ аннотирования документов в коде C#, особенно для контроллеров и методов действий в веб-API ASP.NET Core. Добавляя комментарии XML, вы можете автоматически генерировать документацию Swagger и улучшать читаемость документации API. Вот основные шаги по использованию комментариев XML для аннотирования контроллеров веб-API и методов действий:

Включите комментарии XML: Включите комментарии XML-документации в свойствах проекта. в визуальном В Studio его можно включить с помощью параметра «Создать файл XML-документа» на вкладке «Создать» свойств проекта.

Напишите XML-комментарии: Добавьте комментарии XML в места комментариев контроллеров и методов действий. Например:

/// <summary>
/// контроллер действий пользователя
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
    /// <summary>
    /// Получить всю информацию о пользователе
    /// </summary>
    /// <returns>Список пользователей</returns>
    [HttpGet]
    public IEnumerable<User> GetUsers()
    {
        // Реализуйте логику
    }

    /// <summary>
    /// Получить информацию о пользователе на основе идентификатора пользователя
    /// </summary>
    /// <param name="id">ID пользователя</param>
    /// <returns>Информация о пользователе</returns>
    [HttpGet("{id}")]
    public ActionResult<User> GetUserById(int id)
    {
        // Реализуйте логику
    }

    // XML-комментарии для других инструкций
}

Создайте документацию Swagger: Запустите приложение и посетите Сваггер пользовательском интерфейсе, вы обнаружите, что документы в комментариях XML автоматически сопоставляются с соответствующими частями API, что повышает качество и читаемость документации API.

Совет: XML-аннотации предоставляют разработчикам интуитивно понятный и стандартизированный способ описания различных частей API, что очень полезно для создания документации Swagger и других инструментов документации.

2.2 Аннотации Swagger

Аннотации Swagger используются для улучшения и настройки сгенерированных документов API с помощью определенных аннотаций при использовании Swagger в веб-API ASP.NET Core. Эти аннотации могут предоставить более подробную информацию, что делает созданную документацию Swagger более точной и полезной. Ниже приведены некоторые часто используемые аннотации Swagger и их использование:

[SwaggerOperation]： Используется для обозначения метода работы контроллера с описанием и подробной информацией о работе.

[HttpGet("{id}")]
[SwaggerOperation(Summary = "Get user by ID", Description = "Retrieve user details by providing user ID.")]
public ActionResult<User> GetUserById(int id)
{
    // Реализуйте логику
}

[SwaggerResponse]： Информация ответа, используемая для указания метода работы, включая код состояния HTTP и тип ответа.

[HttpGet("{id}")]
[SwaggerResponse(StatusCodes.Status200OK, "User details retrieved successfully", typeof(User))]
[SwaggerResponse(StatusCodes.Status404NotFound, "User not found")]
public ActionResult<User> GetUserById(int id)
{
    // Реализуйте логику
}

[SwaggerRequestExample] и [SwaggerResponseExample]： Используется для предоставления запроса и ответа из примеров.,чтобы объяснить более понятноAPIизиспользовать Способ。

[HttpPost]
[SwaggerRequestExample(typeof(User), typeof(UserExample))]
[SwaggerResponse(StatusCodes.Status201Created, "User created successfully", typeof(User))]
[SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid user data")]
public ActionResult<User> CreateUser([FromBody] User user)
{
    // Реализуйте логику
}

[SwaggerSchema]： Используется для указания моделииз额外属секс,нравитьсяtitle、descriptionждать,чтобы настроить модель В Сваггере в документеизподарок。

[SwaggerSchema(Title = "User Model", Description = "Represents a user in the system.")]
public class User
{
    // Свойства модели
}

проходитьиспользовать Эти Сваггер-аннотация,Разработчики имеют более гибкий контроль над генерациейизSwaggerдокументизсодержаниеи Формат,для удовлетворения конкретныхиздокументнуждатьсяикомандные нормы。Это понятно для построения、подробныйизAPIдокументда非常有帮助из。

2.3 Рекомендации по улучшению читабельности документов

улучшатьдокументчитаемыйсексда编写APIдокумент时из Одна из ключевых целей,Это помогает разработчикам и другим членам команды легко понять правильный API. Вот несколько рекомендаций по соблюдению читаемости документов:

1. Четкая структура: 组织документ时采用清晰изструктура,Например, заголовки, подзаголовки, списки и т. д.,Помогает читателям легче находить и понимать информацию.
2. Краткое и понятное описание: использоватькраткий и ясныйизязык,избегатьиспользоватьслишком сложныйизтермин,Убедитесь, что документация проста для понимания.
3. Пример и пример кода: 提供подробныйиз Примери Пример代码,продемонстрироватьAPIизиспользовать Способ。это помогает开发者更好地理解нравиться何调用API。
4. использовать Комментарий： В коде постоянно используются комментарии, особенно XML-комментарии или Сваггер-аннотации, предоставляющие ключевую информацию. Эти аннотации могут автоматически генерировать документацию API.
5. использовать диаграммы и графики: использоватьдиаграмма、графикаи表格ждать可视化元素,чтобы объяснить более интуитивноAPIизструктураи Принцип работы。
6. Инструкции по устранению ошибок: существоватьдокументсерединаподробный描述ошибка处理机制,Включая возможные ошибки, код ошибки、Часто задаваемые вопросы и решения.
7. Своевременные обновления: Убедитесь, что документация актуальна и соответствует фактическому коду. Своевременно обновляйте документацию, чтобы отразить последние изменения в API.
8. Обеспечить функцию поиска: Если содержание документа большое, функция поиска может помочь пользователям быстро найти интересующую их информацию.
9. Инструкции по контролю версий: Если существует несколько версий API, в документации должны быть четко указаны изменения в каждой версии, чтобы разработчики могли выбрать версию, соответствующую их потребностям.
10. Дополнительные ресурсы: существоватьдокументсередина提供附加资源链接,нравиться Пример应用程序、Учебники или другие полезные инструменты для пониманияAPIизматериал。
11. Предоставьте часто задаваемые вопросы (FAQ): Собирайте часто задаваемые вопросы и отвечайте на них, чтобы пользователи могли быстро находить решения при возникновении проблем.

that перенимает эти лучшие практики,Может极大地улучшатьAPIдокументизчитаемыйсекс,Это поможет разработчикам и членам команды поддерживать API.

3. Настройка документов Swagger.

3.1 Изменение конфигурации Swagger

В АСП.НЕТ Core Web APIсередина,ты можешьпроходить ИсправлятьSwaggerКонфигурациявыполнятьSwaggerдокументизсделанный на заказ。Swashbuckle.AspNetCoreпредоставляет набор Конфигурация Параметры,Позволяет корректировать сборкуизSwaggerдокументиз Появлениеи Поведение。Вот некоторые общиеизSwaggerКонфигурация Параметрыинравиться何Исправлятьонииз Пример：

Измените информацию о документе Swagger: ты можешь ИсправлятьSwaggerдокументиз Базовыйинформация,Например, название, версия и описание.

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo 
    { 
        Title = "Your API Name", 
        Version = "v1", 
        Description = "Description of your API"
    });
});

Скрыть контроллеры: нравиться果你想要隐藏特定из Контроллер или метод действия,ты можешьиспользоватьIgnoreApi特секс或проходить Конфигурация Исключать。

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.IgnoreApi(typeof(AdminController)); // Скрытьадминконтроллер
});

Настройте внешний вид пользовательского интерфейса: Вы можете настроить Swagger с помощью UIизстильитема,сделать так, чтобы оно подходило тебеиз应用程序Появление。

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.InjectStylesheet("/custom.css"); // Знакомство с таблицей стилей Настроить
});

Пользовательские правила генерации Swagger: проходить КонфигурацияDocumentFilterиOperationFilter,ты можешь编写НастроитьизSwaggerСоздать правила,для удовлетворения конкретныхизнуждаться。

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.DocumentFilter<MyCustomDocumentFilter>();
    c.OperationFilter<MyCustomOperationFilter>();
});

以上只да一些сделанный на заказSwaggerдокументиз Базовый Конфигурация Пример。Swashbuckle.AspNetCoreпредлагает большеиз Конфигурация Параметры,Позволяет тонко настроить сборку.изSwaggerдокумент。проходитьчитатьSwashbuckle.AspNetCoreиздокумент,ты можешь深入了解可用из Конфигурация Параметрыинравиться何использоватьони。

3.2 Настройка внешнего вида пользовательского интерфейса

Пользовательский Swagger Внешний вид пользовательского интерфейса является общим требованием, особенно если вы хотите, чтобы документация API соответствовала общему стилю приложения. Вот несколько В АСП.НЕТ Core Web APIсередина Пользовательский Swagger Типичные варианты внешнего вида пользовательского интерфейса:

Представляем пользовательскую таблицу стилей: В Сваггере UIсередина,ты можешьпроходитьпредставлять НастроитьизCSSстиль表来Исправлять Появление。первый,Создайте файл, содержащий НастроитьстильизCSSдокумент（例нравиться,custom.css）,Тогда В Сваггере Добавьте эту таблицу стилей в конфигурацию пользовательского интерфейса:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.InjectStylesheet("/custom.css"); // Знакомство с таблицей стилей Настроить
});

Корректированиетемаицвет： Swagger UI允许你Корректированиетемаицвет,Приведите его в соответствие с приложениемиз Появление。ты можешьпроходить КонфигурацияThemeиSwaggerEndpointосознать：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.InjectStylesheet("/custom.css"); // Знакомство с таблицей стилей Настроить
    c.ConfigObject.Add("theme", "dark"); // Установить тему
});

Здесь приведен пример «темного», вы можете выбирать разные темы в соответствии с вашими потребностями.

НастроитьLogoизаголовок： проходить КонфигурацияSwaggerUIOptions,ты можешьдобавить в НастроитьLogoизаголовок,делатьSwagger Пользовательский интерфейс больше соответствует идентичности вашего бренда.

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.InjectStylesheet("/custom.css"); // Знакомство с таблицей стилей Настроить
    c.ConfigObject.Add("theme", "dark"); // Установить тему
    c.DocumentTitle = "Your Custom Title"; // Установить заголовок Настроить
    c.RoutePrefix = "swagger"; // Установить префикс маршрутизации
    c.HeadContent = "<link rel='icon' type='image/png' href='/custom-logo.png' />"; // 设置НастроитьLogo
});

здесьиз"/custom-logo.png"да НастроитьLogoизпуть。

Комбинируя эти параметры конфигурации, вы можете полностью настроить Swagger в соответствии со своими потребностями. UIиз Появление,делать其与你из Стиль приложения соответствует。Корректированиестиль、тема、цветиLogo都能够улучшатьдокументизаттракционичитаемыйсекс。

3.3 Сокрытие конфиденциальной информации

В Сваггере документ иногда требует Скрыть конфиденциальную информацию, чтобы гарантировать, что конфиденциальные данные не просочятся в существующие документы. Вот несколько В АСП.НЕТ Core Web Распространенные способы скрыть конфиденциальную информацию в API:

использовать SwaggerIgnoreAttribute： Вы можете создать индивидуальный SwaggerIgnoreAttribute,и Воля其应用于类或属секс,чтобы указать Swagger игнорировать класс или свойство.

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Property)]
public class SwaggerIgnoreAttribute : Attribute { }

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }

    [SwaggerIgnore]
    public string Password { get; set; }
}

Затем убедитесь, что В Включите эту функцию в Сваггере Конфигурация:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.SchemaFilter<SwaggerIgnoreFilter>(); // Включить SwaggerIgnoreFilter
});

SwaggerIgnoreFilter это реализация ISchemaFilter Класс интерфейса, используемый для фильтрации свойств в документах Swagger.

использовать XML Комментарии скрыты: использовать XML Аннотации позволяют скрыть или изменить определенную информацию в документе. Для конфиденциальной информации вы можете добавить <inheritdoc cref="!PropertyName" /> для исключения определенных атрибутов.

/// <summary>
/// Информация о пользователе
/// </summary>
public class User
{
    /// <summary>
    /// ID пользователя
    /// </summary>
    public int Id { get; set; }

    /// <summary>
    /// имя пользователя
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// Пароль (не показан в документе)
    /// </summary>
    /// <inheritdoc cref="!Password" />
    public string Password { get; set; }
}

проходить inheritdoc cref="!Password",Вы можете указать Swagger не показывать атрибут пароля в существующем документе.

Пользовательский фильтр: проходитьвыполнить Swagger Интерфейс фильтра: вы можете написать собственную логику для управления тем, какая информация отображается в Swagger в документе. Например, реализовать IOperationFilter Выполните настройку рабочего уровня.

public class HidePasswordOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var ignoredProperties = context.ApiDescription.ActionDescriptor.EndpointMetadata
            .Where(em => em.GetType() == typeof(SwaggerIgnoreAttribute))
            .Select(em => (SwaggerIgnoreAttribute)em);

        foreach (var ignoredProperty in ignoredProperties)
        {
            var propertyToRemove = operation.RequestBody.Content
                .First()
                .Value
                .Schema
                .Properties
                .FirstOrDefault(p => p.Key.ToLower() == ignoredProperty.PropertyName.ToLower());

            if (propertyToRemove.Key != null)
            {
                operation.RequestBody.Content.First().Value.Schema.Properties.Remove(propertyToRemove.Key);
            }
        }
    }
}

Тогда В Сваггере Конфигурациясередина启用Пользовательский фильтр:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.OperationFilter<HidePasswordOperationFilter>(); // Включить фильтр Настроить
});

проходитьвышеуказанный метод,ты можешь根据具体нуждаться隐藏或КорректированиеSwaggerдокументсерединаиз敏感информация,убеждатьсядокумент不会泄露不必要издеталь。

4. Безопасность и контроль разрешений

4.1 Вопросы безопасности для документов Swagger

Очень важно обеспечить безопасность документов Swagger, особенно в общедоступных или производственных средах. Вот несколько предложений по повышению безопасности документов Swagger:

Контроль доступа: Ограничить развязность UIиSwagger JSONизправа доступа,убеждаться只有Авторизоватьиз Пользователь или система могут получить доступ。Можетпроходитьсередина间件и过滤器осознать这一点。

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
});

// Добавьте промежуточное программное обеспечение контроля доступа
app.Use(async (context, next) =>
{
    // существуют Здесь реализована логика контроля доступа
    // Например, проверьте информацию аутентификации пользователя.
    // Если пользователь не авторизован, вы можете вернуться 403 Forbidden или перенаправить на страницу входа
    await next.Invoke();
});

API-ключи Аутентификация： Если ваш API требует аутентификации, убедитесь, что Swagger Пользовательский интерфейс также может адаптироваться к этим требованиям. ты можешь Сваггере Конфигурациясерединадобавить вAPI-ключ或Аутентификацияинформация。

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.AddSecurityDefinition("apiKey", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.ApiKey,
        Name = "Authorization",
        In = ParameterLocation.Header,
        Description = "API Key Authorization"
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "apiKey"
                }
            },
            new string[] { }
        }
    });
});

Это добавит поле ввода ключа API в пользовательский интерфейс Swagger и включит в запрос информацию для аутентификации.

Скрыть документы производственной среды: существовать生产环境середина,Возможно, вы не захотите раскрывать его внешнему миру.Swaggerдокумент。ты можешьпроходитьсуществоватьзапускатьдокументсерединадобавить вусловная проверка, чтобы скрытьSwaggerКонфигурация。

#if DEBUG
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
});
#endif

Таким образом, Swagger будет включен только в режиме отладки.

Swagger Пользовательский интерфейс установил пароль: В некоторых случаях вам может понадобиться Swagger UIИметь пароль доступа。Можетпроходитьдобавить всередина间件осознать Базовыйиз Аутентификация。

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.RoutePrefix = "swagger";
});

app.Use(async (context, next) =>
{
    var endpoint = context.GetEndpoint();
    if (endpoint?.Metadata.GetMetadata<SwaggerEndpointAttribute>() != null)
    {
        var isAuthenticated = context.User.Identity.IsAuthenticated;
        if (!isAuthenticated)
        {
            context.Response.StatusCode = 401; // Unauthorized
            return;
        }
    }
    await next.Invoke();
});

Приведенный выше код Волясуществовать Посетите Сваггер При проверке пользовательского интерфейса проверьте, прошел ли пользователь аутентификацию. Если он не прошел проверку подлинности, будет возвращена ошибка 401. Unauthorized。

Регулярный обзор и обновления: Регулярно просматривайте информацию в документации Swagger, чтобы гарантировать ее точность, отсутствие утечки конфиденциальной информации и соответствие новейшим стандартам безопасности.

он принимает эти соображения безопасности,Может更好地保护Swaggerдокумент不受未经Авторизоватьиздоступ,иубеждаться其серединаизинформация不会泄露敏感информация。

4.2 Интегрированная аутентификация и авторизация

В Интеграция аутентификации и авторизации в Сваггере — это важная практика безопасности, которая гарантирует, что только аутентифицированные и авторизованные пользователи смогут получить доступ к документам API. Вот несколько В АСП.НЕТ Core Web APIсерединавыполнитьSwaggerинтегрированный Аутентификацияи Авторизоватьизшаг：

Включите аутентификацию и авторизацию: В АСП.НЕТ Coreсередина,первыйубеждаться你из应用程序启用了Аутентификацияи Авторизовать。ты можешьиспользоватьвстроенныйиз Аутентификация系统或интегрированный第三方Аутентификация提供者。

// Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // Добавить службу аутентификации
    services.AddAuthentication(options =>
    {
        options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    }).AddJwtBearer(options =>
    {
        // Конфигурация JWT Bearer Сертификация
        // ...
    });

    // Добавить сервис авторизации
    services.AddAuthorization(options =>
    {
        options.AddPolicy("AdminOnly", policy => policy.RequireRole("Admin"));
    });

    // Другие услуги Конфигурация...
}

Конфигурация Swagger Сертификация: В Сваггере Конфигурациясередина,добавить всоответствующийиз Сертификация Конфигурация,以убеждатьсяSwagger Пользовательский интерфейс способен корректно взаимодействовать с системой аутентификации и авторизации.

// Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // ...

    // КонфигурацияSwaggerСлужить    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });

        // добавить в JWT Bearer Сертификация Конфигурация
        var securityScheme = new OpenApiSecurityScheme
        {
            Name = "Authorization",
            BearerFormat = "JWT",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.ApiKey,
            Scheme = "Bearer",
            Description = "Enter 'Bearer {token}' to authenticate."
        };
        c.AddSecurityDefinition("Bearer", securityScheme);

        // добавить в Авторизовать Конфигурация
        var securityRequirement = new OpenApiSecurityRequirement
        {
            { securityScheme, new List<string>() }
        };
        c.AddSecurityRequirement(securityRequirement);

        // Необязательно: Скрыть Swagger UI из "Authorize" кнопка
        c.AddFilter<HideAuthorizedOperationsFilter>();
    });

    // ...
}

Swagger UI Конфигурация Сертификациякнопка： Чтобы сделать Swagger UIпоказывать Сертификациякнопка,ты можешьдобавить водинJavaScriptдокумент,и В Сваггере Введено во время настройки Должендокумент。

// wwwroot/swagger-ui-authorization.js

window.onload = function () {
    const authorizeBtn = document.querySelector(".authorize-wrapper button");

    if (authorizeBtn) {
        authorizeBtn.addEventListener("click", function () {
            const token = prompt("Enter your JWT token");
            if (token) {
                // Воля token добавить в прибыть Authorization голова
                const input = document.querySelector("input[name='token']");
                if (input) {
                    input.value = "Bearer " + token;
                    input.dispatchEvent(new Event("change"));
                }
            }
        });
    }
};

существовать Swagger Введено во время настройки JavaScript документ:

// Startup.cs

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...

    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");

        // представлять Настроить JavaScript документ
        c.InjectJavascript("/swagger-ui-authorization.js");
    });

    // ...
}

эти шаги,Swagger UI отобразит “Authorize” кнопка,用户Можетпроходитьвходить JWT Token 进行Аутентификация。убеждаться你из Авторизовать策略与Конфигурациясерединаизпоследовательный,чтобы ограничить доступ к пользовательскому интерфейсу Swagger только авторизованным пользователям.

4.3 Контроль разрешений в Swagger

В Сваггересередина进行权限控制даубеждаться只有Авторизовать用户能够доступииспользоватьAPIдокументизважная часть。以下да一些В АСП.НЕТ Core Web Шаги по реализации контроля разрешений в Swagger в API:

Конфигурация Swagger Сертификация: В Сваггере Конфигурациясередина,первыйубеждаться已经Конфигурация了соответствующийиз Аутентификация方案,нравитьсяJWT Сертификат на предъявителя.

// Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // ...

    // КонфигурацияSwaggerСлужить    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });

        // добавить в JWT Bearer Сертификация Конфигурация
        var securityScheme = new OpenApiSecurityScheme
        {
            Name = "Authorization",
            BearerFormat = "JWT",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.ApiKey,
            Scheme = "Bearer",
            Description = "Enter 'Bearer {token}' to authenticate."
        };
        c.AddSecurityDefinition("Bearer", securityScheme);

        // добавить в Авторизовать Конфигурация
        var securityRequirement = new OpenApiSecurityRequirement
        {
            { securityScheme, new List<string>() }
        };
        c.AddSecurityRequirement(securityRequirement);

        // Необязательно: Скрыть Swagger UI из "Authorize" кнопка
        c.AddFilter<HideAuthorizedOperationsFilter>();
    });

    // ...
}

Настроить Swagger Фильтр документов: 创建один НастроитьизSwaggerФильтр документов,Должен过滤器Воля По словам пользователяиз Авторизовать角色过滤掉不可见изAPI。

// CustomSwaggerDocumentFilter.cs

public class CustomSwaggerDocumentFilter : IDocumentFilter
{
    private readonly IAuthorizationService _authorizationService;

    public CustomSwaggerDocumentFilter(IAuthorizationService authorizationService)
    {
        _authorizationService = authorizationService;
    }

    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // Получить пользователяиз角色информация,здесьиз逻辑Может根据实际情况Корректирование
        var userRoles = context.ApiDescriptions
            .SelectMany(apiDesc => apiDesc.ActionDescriptor.EndpointMetadata
                .OfType<AuthorizeAttribute>()
                .SelectMany(attr => attr.Roles.Split(',')))
            .Distinct();

        // 移除未Авторизовать用户из API
        var pathsToRemove = swaggerDoc.Paths
            .Where(pair => pair.Value.Operations.Any(operation =>
                operation.Value.Extensions.ContainsKey("x-roles") &&
                !userRoles.Any(role => operation.Value.Extensions["x-roles"].ToString().Split(',').Contains(role))))
            .Select(pair => pair.Key)
            .ToList();

        foreach (var path in pathsToRemove)
        {
            swaggerDoc.Paths.Remove(path);
        }
    }
}

использовать Настроить Swagger Фильтр документов: В Сваггере Конфигурациясерединаиспользовать Только что созданоиз Пользовательский SwaggerФильтр документов。

// Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // ...

    // добавить вSwaggerСлужить
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });

        // добавить в JWT Bearer Сертификация Конфигурация
        var securityScheme = new OpenApiSecurityScheme
        {
            Name = "Authorization",
            BearerFormat = "JWT",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.ApiKey,
            Scheme = "Bearer",
            Description = "Enter 'Bearer {token}' to authenticate."
        };
        c.AddSecurityDefinition("Bearer", securityScheme);

        // добавить в Авторизовать Конфигурация
        var securityRequirement = new OpenApiSecurityRequirement
        {
            { securityScheme, new List<string>() }
        };
        c.AddSecurityRequirement(securityRequirement);

        // добавить в Настроить Swagger Фильтр документов
        c.DocumentFilter<CustomSwaggerDocumentFilter>();
    });

    // ...
}

так,只有具有正确Авторизовать角色из Возможности пользователя В Сваггере UIсередина看到相关API。убеждаться根据实际из Авторизовать策略и角色информация进行适当из Корректирование。это помогаетсуществоватьдокументсередина保护敏感информация,иубеждаться只有经过Авторизоватьиз Пользователи могут просматриватьииспользоватьAPI。

5. Резюме

В АСП.НЕТ Core Web APIсередина,проходитьинтегрированныйSwaggerвыполнить了自动生成APIдокументиз Функция。первый,проходить Установить Сваггер Пакет NuGet, конфигурация службы Swagger и промежуточное программное обеспечение для работы с Интернетом. APIсовместная работа。проходитьXML-комментариии Сваггер-аннотация,Предоставьте подробную информациюизAPIинформация,Включая операции, ответы и т. д. Для улучшения читаемости документа,Применяются лучшие практики, такие как четкая структура, краткое описание и пример кода. применить Изменить SwaggerКонфигурацияи Настроить внешний вид пользовательского интерфейса,Сделайте документ более соответствующим потребностям команды и стилю приложения. в то же время,Обсуждаются вопросы безопасности,Включая контроль доступа, ключ API, пароль настройки пользовательского интерфейса Swagger и т. д.,для обеспечения безопасности документов. наконец,Введение в контроль разрешенийизметод,проходитьSwaggerФильтр документов,只允许具有Авторизовать角色из Связанное с представлением пользователяAPI,进一步保障敏感информацияиз Безопасность。Этишаг共同构建了один Безопасность、читаемый、Простота в использованииизSwaggerдокумент。