Swagger webservice doc generation

Swagger Javadoc

Link:

https://github.com/ryankennedy/swagger-jaxrs-doclet

?

?

Usage:

Allow swagger definition json file to begenerated on building the maven project. Add the following to your rest api project pom file

?

<build>

??? <plugins>?

?????? <plugin>

???????????<groupId>org.apache.maven.plugins</groupId>

???????????<artifactId>maven-javadoc-plugin</artifactId>

???????????<version>2.9.1</version>

???????????<executions>

?????????????? <execution>

???????????????????<id>generate-service-docs</id>

???????????????????<phase>generate-resources</phase>

?????????????????? <configuration>

????????????????????? <doclet>com.hypnoticocelot.jaxrs.doclet.ServiceDoclet</doclet>

????????????????????? <docletArtifact>

???????????????????????? <groupId>com.hypnoticocelot</groupId>

???????????????????????? <artifactId>jaxrs-doclet</artifactId>

???????????????????????? <version>0.0.4-SNAPSHOT</version>

?</docletArtifact>??????????????????????

?<reportOutputDirectory>

??? ${project.build.outputDirectory}

?</reportOutputDirectory>

????????????????????? <useStandardDocletOptions>false</useStandardDocletOptions>

?<additionalparam>

?? -apiVersion1 -docBasePath /apidocs -apiBasePath https://api.stubhub.com/

?</additionalparam>

?????????????????? </configuration>

?????????????????? <goals>

????????????????????? <goal>javadoc</goal>

?????????????????? </goals>

?????????????? </execution>

???????????</executions>

???????</plugin>

??? </plugins>

?</build>

?

?

mvn clean package ???? output is generated in target/classes/apidocs ????

Pros:

Can generate swagger definition based on jax-rs annotations only,you don’t have to add any swagger annotations. Not invasive.

?

Limitation:

The default plugin provided supports only jdk 1.7 javadoc,you have to recompile the source with jdk 1.6 tools.jar to support 1.6 javadoc

?

If at class level,api path is declared as “/”,the api json file is not generated

This has been fixed by me by modifying the source code

?

If at class level,no path annotation isadded,the api json file is not generated

?

?

Swagger cxf integration

Link:

https://github.com/wordnik/swagger-core/wiki/Java-CXF-Quickstart

?

Usage:

Allow you to view swagger json definition at runtime,there is an additional swagger doc rest endpoint in additional to your original rest webservice

?

?

Maven dependencies

?<dependency>

?? <groupId>com.wordnik</groupId>

?? <artifactId>swagger-jaxrs_2.10</artifactId>

?? <version>1.3.0</version>

?</dependency>???????

?

?

Cxf spring config file

<!-- Swagger API listing resource -->

<bean id="swaggerResourceJSON"class="com.wordnik.swagger.jaxrs.listing.ApiListingResourceJSON"/>

?

<!-- Swagger writers -->

<bean id="resourceWriter"class="com.wordnik.swagger.jaxrs.listing.ResourceListingProvider"/>

<bean id="apiWriter"class="com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider"/>

?

<bean class="org.apache.cxf.jaxrs.JAXRSServerFactoryBean"init-method="create">

?<property name="address" value="/" />

?<property name="serviceBeans">

???<list>

?????<!-- your resources go here -->

?????<!-- ... -->

?????<!-- ... -->

?????<!-- Swagger API Listing resource -->

?????<ref bean="swaggerResourceJSON" />

???</list>

?</property>

?<property name="providers">

???<list>

?????<!-- any other providers you need go here -->

?????<!-- ... -->

?????<!-- ... -->

?????<!-- required for writing swagger classes -->

?????<ref bean="resourceWriter" />

?????<ref bean="apiWriter" />

???</list>

?</property>

</bean>

?

<bean id="swaggerConfig" class="com.wordnik.swagger.jaxrs.config.BeanConfig">

? <propertyname="resourcePackage" value="com.wordnik.swagger.sample.resource"/>

? <propertyname="version" value="1.0.0"/>

? <propertyname="basePath" value="http://localhost:8002/api"/>

? <propertyname="title" value="Petstore sample app"/>

? <propertyname="description" value="This is a app."/>

? <propertyname="contact" value="apiteam@wordnik.com"/>

? <propertyname="license" value="Apache 2.0 License"/>

? <propertyname="licenseUrl" value="http://www.apache.org/licenses/LICENSE-2.0.html"/>

? <property name="scan"value="true"/>

</bean>

?

The highlighted properties are important

You will see an additional endpoint in youwadl file and swagger json file in

http://<host>/<context>/api-docs

?

?

Pros:

API definitions are always most up to date,allow you to view swagger definition at run time

?

Limitations:

You need to add swagger annotations to yoursource

It will not work if:

You don’t have @Api annotation in yourservice class

You have @Api annotation but not any @ApiOperation in your service method

?

Certain API definitions are not generated properly,even annotations are there. (Not too sure about the reasons)

?

?

Swagger maven plugin

Link:

https://github.com/kongchen/swagger-maven-plugin

?

Usage:

Allow swagger definition json file to begenerated on building the maven project， similar to the Javadocplugin

?

<pluginRepositories>

? ???? <pluginRepository>

??? ????? <id>sonatype-snapshot</id>

??? ????? <url>https://oss.sonatype.org/content/repositories/snapshots/</url>

??? ????? <releases>

????????? ? <enabled>false</enabled>

??? ????? </releases>

??? ????? <snapshots>

????????? ? <enabled>true</enabled>

??? ????? </snapshots>

? ??? </pluginRepository>

?? </pluginRepositories>

?

?? <build>

????? <plugins>

??????????<plugin>

????????????<groupId>com.github.kongchen</groupId>

????????????<artifactId>swagger-maven-plugin</artifactId>

????????????<version>2.0</version>

????????????<configuration>

?????????????? <apiSources>

????????????????? <apiSource>

???????????????????? <locations>com.stubhub.apitest</locations>

???????????????????? <apiVersion>v1</apiVersion>

???????????????????? <basePath>http://www.stubhub.com.com</basePath>

???????????????????? <outputTemplate>

????????????????????? https://raw.github.com/kongchen/api-doc-template/master/v2.0/markdown.mustache

???????????????????? </outputTemplate>

???????????????????? <outputPath>generated/strapdown.html</outputPath>

???????????????????? <!--swaggerUIDocBasePath>http://www.stubhub.com/apidocsf</swaggerUIDocBasePath-->

???????????????????? <swaggerDirectory>generated/apidocs</swaggerDirectory>

???????????????????? <!--uSEOutputFlatStructure>false</uSEOutputFlatStructure-->

???????????????????? <!--mustacheFileRoot>${basedir}/src/main/resources/</mustacheFileRoot-->

????????????????? </apiSource>

?????????????? </apiSources>

????????????</configuration>

????????????<executions>

?????????????? <execution>

????????????????? <phase>compile</phase>

??????????????????? <goals>

?????????????????????? <goal>generate</goal>

??????????????????? </goals>

?????????????? </execution>

????????????</executions>

?????????</plugin>

????? </plugins>

?? </build>??

?

The highlighted package specifies thepackage to scan for swagger apis

?

Mvn clean compile?? output is generated in generated/apidocs

?

Pros:

Can generate swagger API definition withoutserver running

?

Limitations:

You need to add swagger annotations to yoursource

It will not work if:

You don’t have @Api annotation in yourservice class