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
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 /
După cum este recomandat în mesaj, ar trebui să rezolvați în mod independent situația și există mai multe opțiuni:
- selectați o singură metodă
- faceți o metodă cu toți parametrii
- modificați generarea unui document
Prima și a doua metodă sunt implementate prin setarea c.ResolveConflictingActions (Func
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:
- creați propria clasă MySwaggerGenerator: ISwaggerProvider
- în depozitul Swashbuckle de pe GitHub, găsiți SwaggerGenerator.cs (este aici)
- Copiați metoda GetSwagger și alte metode aferente
- duplicarea variabilelor interne și inițializarea acestora în constructorul clasei lor
- î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).