Configurarea swapbuckle (swagger) pentru webapi

Configurarea Swapbuckle (Swagger) pentru WebAPI +8

  • 11.12.16 06:22 •
  • ETman •
  • # 317338 •
  • Habrahabr •
  • 11 •
  • 2700

- la fel ca Forbes, doar mai bine.

Suntem fixați în Proiect


Swashbuckle este un pachet NuGet care integrează în WebAPI autogenerarea informațiilor despre noduri în conformitate cu specificația OpenAPI. Această specificație este, de facto, un standard, precum WSDL odată. Pentru a instala, veți avea nevoie de patru pași simpli.

Nuanțe cu WebAPI


Când deploe WebAPI în producție poate fi o problemă cu faptul că fișierul XML lipsește. ansamblul de eliberare a nu le include în mod implicit, dar puteți obține în jurul valorii de acest lucru, prin editarea fișierului csproj. Este necesară adăugarea în PropertyGroup a proiectului fals iar fișierul va rămâne în bin /.

O altă problemă constă în așteptare pentru cei care ascund API pentru proxy. Soluția nu este universală, dar în cazul meu funcționează. Proxy adauga headere la rekvest în care învățăm cum să fie endponitov URL-ul pentru client.

Exemplu de recunoaștere a adresei URL după proxy

Adăugarea de coduri de răspuns

Exemple de adăugare a codurilor de stare

Pentru persoanele lenese, este posibil să adăugați codul generic (de exemplu, 400 (BadRequest) sau 401 (neautorizat) tuturor metodelor simultan. Pentru a face acest lucru, trebuie să implementați interfața IOperationFilter și să înregistrați această clasă utilizând c.OperationFilter();

Exemplu de metoda Apply pentru a adăuga o anumită listă de coduri

Built-in browser


Prin adăugarea acestora în configurația WebAPI, browserul vă va solicita să introduceți datele de autentificare în momentul solicitării. Dificultatea este că nu este convenabil să resetați aceste date la fel de repede ca să le introduceți.


O altă modalitate este mai convenabilă în acest sens, deoarece oferă un formular special. Pentru a activa formularul de autentificare încorporat într-un pachet, trebuie să faceți următoarele:

Implementarea metodei de aplicare a acestui filtru

Adăugarea acestui parametru

Spre exemplu, JS trimitea ascunzătoare lui Swagger

Lucrul cu anteturile obligatorii

Obiective cu metode supraîncărcate


WebAPI vă permite să creați mai multe metode de acțiune pentru un punct final, apelul căruia depinde de parametrii interogării.


Astfel de metode nu sunt acceptate implicit de Swagger și UI va arunca o eroare 500: Nu este acceptată de Swagger 2.0: Operații multiple cu calea 'api /"și metoda"“. Consultați setarea Config - \ "ResolveConflictingActions \" pentru o soluție potențială.

După cum este recomandat în mesaj, ar trebui să rezolvați în mod independent situația și există mai multe opțiuni:

  1. selectați o singură metodă
  2. faceți o metodă cu toți parametrii
  3. modificați generarea unui document

Prima și a doua metodă sunt implementate prin setarea c.ResolveConflictingActions (Func, ApiDescription> conflictingActionsResolver). Esența metodei se reduce la adoptarea mai multor metode conflictuale și la returnarea acestora.

Un exemplu de cum să combinați toți parametrii

Cardinalul Metodă


Cea de a treia cale este mai cardinală și este o abatere de la specificația OpenAPI. Puteți tipări toate punctele finale cu următorii parametri:

Pentru a face acest lucru, trebuie să schimbați modul în care documentul Swagger este generat utilizând IDocumentFilter și să generați singur descrierea.

În viață, această metodă este rareori necesară, așa că am săpat mai adânc. Un alt mod pe care l-aș recomanda numai celor care sunt interesați de Swashbuckle insides este înlocuirea SwaggerGenerator. Acest lucru se face în linia c.CustomProvider (defaultProvider => newSwaggerProvider (defaultProvider)); Pentru a face acest lucru, puteți face acest lucru:

  1. creați propria clasă MySwaggerGenerator: ISwaggerProvider
  2. în depozitul Swashbuckle de pe GitHub, găsiți SwaggerGenerator.cs (este aici)
  3. Copiați metoda GetSwagger și alte metode aferente
  4. duplicarea variabilelor interne și inițializarea acestora în constructorul clasei lor
  5. înregistrați în configurația Swagger

Inițializarea variabilelor interne


După aceea, trebuie să găsiți locul var paths = GetApiDescriptionsFor (apiVersion). Acesta este locul unde sunt create căile. De exemplu, pentru a obține ceea ce presupune exemplul, trebuie să înlocuiți GroupBy () cu .GroupBy (apiDesc => apiDesc.RelativePath).

literatură

Articole similare