În acest articol, vă voi arăta cum să conectați Swagger la un proiect Maven care implementează serverele REST utilizând specificația JAX-RS - RESTEasy. Articolul va descrie legătura dintre Swagger și proiect, folosirea documentației serviciilor REST cu ajutorul adnotărilor, descrierea vizualizării documentației prin interfața web.
Conectați Swagger la proiect
Conectarea dependențelor Maven
În primul rând, trebuie să adăugăm dependența Swagger de proiectul Maven. Deoarece vom conecta Swagger la RESTEasy, vom adăuga dependența corespunzătoare.
La momentul redactării manualului, versiunea curentă este 1.5.6.
Trebuie remarcat faptul că Swagger are o reparație moștenită. Grupul de depozitare lagecyId = com.wordnik. Trebuie să țineți cont de acest lucru și să nu amestecați dependențele!
Mai multe detalii pot fi citite aici.
Configurarea proiectului
Apoi, trebuie să conectăm ascultătorii la proiect, astfel încât Swagger să poată determina automat adnotările și să genereze documentația.
Am făcut configurarea folosind descendentul clasei javax.ws.rs.core.Application.
Setarea va arăta astfel:
Mai multe detalii despre alte metode de conectare pot fi citite aici.
Configurarea lui Swagger
Apoi, trebuie să configurați setările Swagger-ului în sine. Am făcut acest lucru în constructorul aceluiași moștenitor de clasă Application.
Mai multe detalii despre alte metode de personalizare pot fi găsite aici.
Mai întâi, voi descrie adnotările, care sunt obligatorii pentru documentația corectă și afișarea corectă a serviciilor REST pe Swagger-UI.
Pentru ca swagger să determine că serviciile REST sunt în clasă, această clasă trebuie marcată cu adnotarea @Api. În parametrii acestei adnotări, puteți specifica numele secțiunii în care vor fi localizate REST-urile în interfața de utilizare și specificați descrierea acestei secțiuni.
De exemplu:
@ApiOperation
Adnotarea @ApiOperation trebuie specificată prin metoda serviciului REST. De asemenea, în parametrii săi puteți specifica descrierea serviciului.
Alte adnotări
Pentru a specifica în mod explicit ascunzătoarele care sunt obligatorii pentru un anumit serviciu, puteți utiliza adnotarea
Pentru a specifica explicit obiectul de răspuns, puteți folosi adnotarea @ApiResponse. Acest lucru este util dacă, ca răspuns al serverului REST, obiectul Responce revine.
Mai multe informații despre toate adnotările pot fi găsite aici.
Pentru a seta urlul implicit, trebuie să editați codul sursă pentru fișierul index.html
După aceasta vom vedea documentația serviciilor noastre REST. Puteți solicita serviciile REST direct de la UI.
În cazul în care Swagger emite o eroare nu poate fi preluată, va trebui să configurați antetele CORS pe serverul în care este încorporată aplicația noastră, trebuie să adăugăm antetul Access-Control-Allow-Origin: *
Un exemplu de mapare a serviciilor REST către UI:
Lista serviciilor REST pe Web-UI:
Forma de informații detaliate despre serviciul REST și posibilitatea trimiterii unei cereri.