Налаштування swashbuckle (swagger) для webapi

Налаштування Swashbuckle (Swagger) для WebAPI +8

  • 11.12.16 6:22 •
  • ETman •
  • # 317338 •
  • Хабрахабр •
  • 11 •
  • 2700

- такий же як Forbes, тільки краще.

Прикручуємо до Проекту


Swashbuckle - це NuGet пакет, що вбудовуються в WebAPI автогенерація інформації про вузли відповідно до специфікації OpenAPI. Ця специфікація є, де-факто, стандартом, як колись WSDL. Для установки, потрібно чотири простих кроки.

Нюанси при Деплой WebAPI


При Деплой WebAPI в продакшн може виникнути проблема з тим, що XML файл відсутній. Реліз збірка не включає їх за замовчуванням, але можна це обійти, підредагувавши csproj файл. Треба в PropertyGroup проекту додати false і файл залишиться в bin /.

Інша проблема підстерігає тих, хто ховає свій API за проксі. Рішення не є універсальним, але в моєму випадку працює. Проксі додає хедери до реквесту, за якими ми дізнаємося, який повинен бути URL ендпонітов для клієнта.

Приклад розпізнання URL за проксі

Додаємо Response Codes

Приклади додавання статус кодів

Для ледачих є можливість додати загальні коду (наприклад 400 (BadRequest) або 401 (Unauthorized)) відразу до всіх методів. Для цього треба реалізувати інтерфейс IOperationFilter і зареєструвати такий клас за допомогою c.OperationFilter() ;.

Приклад методу Apply для додавання деякого списку кодів

Вбудована в Браузер


Додавши їх в конфігурації WebAPI, браузер запропонує ввести дані для аутентифікації в момент виконання запиту. Складність тут в тому, що скинути ці дані не так зручно і швидко, як ввести.


Інший спосіб зручніше в цьому плані, тому що надає спеціальну форму. Щоб включити вбудовану форму аутентифікації в пакет необхідно зробити наступне:

Реалізація методу Apply цього фільтра

Додавання такого параметра

Наприклад JS відправляє хедери в Swagger

Працюємо з Обов'язковими хедер

Ендпоінти з перевантаженістю Методами


WebAPI дозволяє створювати кілька екшн-методів для одного ендпоінта, виклик яких залежить від параметрів запиту.


Такі методи не підтримуються Swagger за замовчуванням і UI видасть помилку 500: Not supported by Swagger 2.0: Multiple operations with path 'api /'And method''. See the config setting - \ "ResolveConflictingActions \" for a potential workaround.

Як і радимо в повідомленні, слід самостійно вирішити ситуацію і є кілька варіантів:

  1. вибрати тільки один метод
  2. зробити один метод з усіма параметрами
  3. змінити генерацію документа

перший і другий способи реалізуються за допомогою настройки c.ResolveConflictingActions (Func, ApiDescription> conflictingActionsResolver). Суть методу зводиться до того, щоб взяти кілька конфліктуючих методів і повернути один.

Приклад того, як об'єднати всі параметри

кардинальний Спосіб


Третій спосіб більш кардинальний і є відходженням від OpenAPI специфікації. Можна вивести всі ендпоінти з параметрами:

Для цього необхідно змінити спосіб генерації документа Swagger за допомогою IDocumentFilter і згенерувати опис самостійно.

У житті такий спосіб рідко коли знадобиться, тому копнемо ще глибше. Ще один спосіб, який я рекомендував би тільки тим, кому цікаві нутрощі Swashbuckle - це замінити SwaggerGenerator. Це робиться в рядку c.CustomProvider (defaultProvider => new NewSwaggerProvider (defaultProvider)) ;. Що б це зробити, можна вчинити так:

  1. створити свій class MySwaggerGenerator: ISwaggerProvider
  2. в репозиторії Swashbuckle на GitHub знайти SwaggerGenerator.cs (він тут)
  3. скопіювати метод GetSwagger і інші пов'язані з ним методи в свій
  4. продублювати внутрішні змінні і форматувати їх в конструкторі свого класу
  5. зареєструвати в конфігурації Swagger

Ініціалізація внутрішніх змінних


Після цього треба знайти місце var paths = GetApiDescriptionsFor (apiVersion). Це те місце, де створюються шляху. Наприклад, щоб отримати те, що в прикладі, необхідно GroupBy () замінити на .GroupBy (apiDesc => apiDesc.RelativePath).

література

Схожі статті