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 apiproject 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}</REPORTOUTP Utdirectory>

<useStandardDocletOptions>false</useStandardDocletOptions>

<additionalparam>-apiversion1-docbasepath/apidocs-apibasepathhttps://api.stubhub.com/</ Additionalparam>

</configuration>

<goals>

<goal>javadoc</goal>

</goals>

</execution>

</executions>

</plugin>

</plugins>

</build>

MVN Clean package output was generated in Target/classes/apidocs

Pros:

Can generate swagger definition based onjax-rs annotations only, you don ' t has to add any swagger annotations. Notinvasive.

Limitation:

The default plugin provided supports ONLYJDK 1.7 Javadoc, you had to recompile the source with JDK 1.6 Tools.jar Tosuppor T 1.6 Javadoc

If at class level, API path is declared as '/', the API JSON file is not generated

This have been fixed by me by modifying Thesource code

If at class level, no path annotation isadded, the API JSON file was not generated

Swagger CXF Integration

Link:

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

Usage:

Allow-to-view swagger JSON Definitionat runtime, there is a additional swagger Doc rest endpoint in additional Toyour 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

<!--...-->

<!--...-->

<!--Swagger API Listing resource--

<ref bean= "Swaggerresourcejson"/>

</list>

</property>

<property name= "Providers" >

<list>

<!--any other providers need go

<!--...-->

<!--...-->

<!--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= "[email protected]"/>

<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'll see a additional endpoint in Youwadl file and swagger json file in

Http://

Pros:

API definitions is always the most up to date,allow your to view swagger definition at run time

Limitations:

You need to add swagger annotations to Yoursource

It won't work if:

You don't have the @Api annotation in Yourservice class

You have @Api annotation and not [email protected] in your service method

Certain API definitions is not generated properly,even annotations is 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 are generated in Generated/apidocs

Pros:

Can generate swagger API definition Withoutserver running

Limitations:

You need to add swagger annotations to Yoursource

It won't work if:

You don't have the @Api annotation in Yourservice class