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.

• https://swagger.io/

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:

1. swagger-annotations: https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X
2. swagger-maven-plugin: https://github.com/kongchen/swagger-maven-plugin
3. swagger-ui: https://github.com/swagger-api/swagger-ui
4. 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/**

Na daný build sme naviazali deployment projekt s krokmi:

1. clean working directory
2. artifact download
3. run script: vytvoriť tar.gz z artefaktu
4. SCP task pre prenesenie artefaktu na cieľové prostredie
5. 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.