Swagger.io je nástroj pro dokumentaci REST API. My jsme ho v jednom z našich projektů použili následujícím způsobem.
Ako dostanem dokumentáciu z mého kódu do Swagger UI?
Swagger UI je JS / HTML / CSS aplikácia, ktorá vizualizuje dokumentáciu ku REST API. Zdrojom dát pre túto aplikáciu je JSON alebo YAML file s popisom API.
V našom prípade sme sa rozhodli použiť nasledujúce technológie:
- swagger-annotations: https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X
- swagger-maven-plugin: https://github.com/kongchen/swagger-maven-plugin
- swagger-ui: https://github.com/swagger-api/swagger-ui
- Bamboo
Zjednodušená logika za celým procesom bola:
anotovať API classes -> za pomoci maven pluginu vygenerovať JSON -> pri Bamboo builde nakopírovať generovaný JSON na server -> cez Swagger UI načítať a zobraziť API
2.1 swagger-annotations
Swagger annotations slúžia na špecifikáciu dodatočných info, ktoré nie je možné zahrnúť do klasických JAX-RS anotácií. Dokumentácia na Github je viac než postačujúca.
2.2 swagger-maven-plugin
Swagger maven plugin preskenuje zdrojové classes a vygeneruje z nich HTML a JSON popis API. HTML súbor sa dá priamo zobraziť. Pre tvorbu HTML používa swagger maven plugin handlebars templates. Konfigurácia pluginu môže byť napríklad nasledovná:
<plugin> <groupid>com.github.kongchen</groupid> <artifactid>swagger-maven-plugin</artifactid> <configuration> <apisources> <apisource> <springmvc>false</springmvc> <schemes>http,https</schemes> <host>${swagger.host}</host> <templatepath>classpath:/templates/swagger/strapdown.html.hbs</templatepath> <!-- cesta ku handlebars templates --> <basepath>/TrackIssue/options</basepath> <locations>cz.morosystems.jira.ebay.trackissue.rest.OptionsRest</locations> <info> <title>eBay SPARC Track issue Options REST API</title> <version>${project.version}</version> <description>Rest service for retrieving suggested options for certain areas of track issue form.</description> </info> <outputpath>${build.directory}/${swagger.generated.htmlPath}/options.html</outputpath> <swaggerdirectory>${build.directory}/${swagger.generated.jsonPath}/options</swaggerdirectory> </apisource> <apisource> <springmvc>false</springmvc> <schemes>http,https</schemes> <host>${swagger.host}</host> <templatepath>classpath:/templates/swagger/strapdown.html.hbs</templatepath> <!-- cesta ku handlebars templates --> <basepath>/TrackIssue/issue</basepath> <locations>cz.morosystems.jira.ebay.trackissue.rest.TrackIssueRest</locations> <info> <title>eBay SPARC Track issue REST API</title> <version>${project.version}</version> <description>Rest service for track issue item</description> </info> <outputpath>${build.directory}/${swagger.generated.htmlPath}/issue.html</outputpath> <swaggerdirectory>${build.directory}/${swagger.generated.jsonPath}/issue</swaggerdirectory> </apisource> </apisources> </configuration> <executions> <execution> <phase>compile</phase> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin>
V našom prípade sme zvolili cestu pre každý resource vlastné <apiSource>. Samozrejme, dalo by sa všetko vygenerovať do jediného JSON – <locations> je možné zadať aj vo forme package name. Po spustení plugin vygeneruje JSON do zložky definovanej v <swaggerDirectory>.
2.3 Ako dostať dokumentáciu do Swagger UI v real time ?
Pre prenesenie JSON sme využili Bamboo. V Bamboo verify builde (spúšťaný po každom commite) sme si nadefinovali artefakt, ktorý reprezentoval práve JSON files vygenerované maven pluginom. Keďže swagger maven plugin generuje defaultne file s názvom swagger.json, vyplatí sa tieto súbory generovať do špeciálnych adresárov (v prípade, že ich máme viac).
V našom prípade nám vznikla nasledujúca štruktúra. Artefakt sme definovali tak, aby bral len obsah adresára target/generated/json/**
target |_ generated |_ html |_ json |_ options | |_ swagger.json | |_ issue |_ swagger.json |
Na daný build sme naviazali deployment projekt s krokmi:
- clean working directory
- artifact download
- run script: vytvoriť tar.gz z artefaktu
- SCP task pre prenesenie artefaktu na cieľové prostredie
- run SSH task: extract tar.gz
Na cieľovom prostredí beží nginx, ktorý staticky obsluhuje swagger ui a zároveň aj directory s nakopírovanými JSON files.
2.4 Swagger UI
Swagger UI je open source aplikácia, ktorú je možné stiahnuť z Github a lokálne si ju upraviť. Po preložení cez npm a gulp sa distribúcia skompiluje do /dist
Problém u Swagger UI je ten, že nedokáže zobraziť lokálne JSON files. Preto je potrebné JSON vystaviť verejne, aby si ho swagger UI stiahol.
Napsat komentář