Swagger webservice doc generation

標籤：rest   swagger   

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}</reportOutputDirectory>

                       <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 is generated in target/classes/apidocs     

Pros:

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

 

Limitation:

The default plugin provided supports onlyjdk 1.7 javadoc, you have to recompile the source with jdk 1.6 tools.jar tosupport 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 thesource 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 definitionat runtime, there is an 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 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 [email protected] 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