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="[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 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