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

Swagger webservice doc generation,古老的榕树,5-wow.com