Java

BUILDING RESTFUL WEB SERVICES PART – 3 Documentation with Swagger

After discussing about Building RESTful Web Services Part – 2,  let’s now understand how to document the REST APIs.

Swagger:

Swagger is a specification for documenting REST APIs. It specifies the format (URL, method, and representation) to describe REST web services. The Swagger UI framework allows both implementer’s and users to interact with the API. It gives clear insight into how the API responds to parameters and options. Swagger responses are in JSON and XML, with additional formats in progress.

Before getting started with swagger documentation, the following pieces of code should be added to the REST application.

1. Add the following code to web.xml file:

<init-param> 
            <param-name>jersey.config.server.provider.classnames</param-name> 
            <param-value> 
                com.wordnik.swagger.jersey.listing.ApiListingResourceJSON, 
                com.wordnik.swagger.jersey.listing.JerseyApiDeclarationProvider, 
                com.wordnik.swagger.jersey.listing.JerseyResourceListingProvider,                
            </param-value> 
</init-param> 
<init-param> 
            <param-name>jersey.config.server.provider.packages</param-name> 
            <param-value>com.wordnik.swagger.jaxrs.json,com.cmsbridge.api</param-value> 
 </init-param>

2. The following dependencies and plugin needs to be added to the pom.xml file:

Dependencies:

<dependency> 
    <groupId>io.swagger</groupId> 
    <artifactId>swagger-hibernate-validations</artifactId> 
    <version>1.5.6</version> 
    <exclusions> 
        <exclusion> 
             <groupId>com.google.guava</groupId> 
             <artifactId>guava</artifactId> 
        </exclusion> 
     </exclusions> 
</dependency> 
<dependency> 
      <groupId>io.swagger</groupId> 
      <artifactId>swagger-core</artifactId> 
      <scope>compile</scope> 
      <version>1.5.3</version> 
      <exclusions> 
          <exclusion> 
               <groupId>javax.ws.rs</groupId> 
               <artifactId>jsr311-api</artifactId> 
          </exclusion> 
          <exclusion> 
               <groupId>com.google.guava</groupId> 
               <artifactId>guava</artifactId> 
          </exclusion> 
      </exclusions> 
</dependency>

Plugin:

<plugin> 
    <groupId>com.github.kongchen</groupId> 
    <artifactId>swagger-maven-plugin</artifactId> 
    <version>3.1.1</version> 
    <configuration> 
        <apiSources> 
           <apiSource> 
                 <springmvc>false</springmvc> 
                 <locations>com.myapplication.api</locations> 
                 <schemes>http</schemes> 
                 <host>host.domain.com</host> 
                 <basePath>/MyApplication/rest</basePath> 
                 <info> 
                    <title>MyApplication Swagger</title> 
                    <version>v1</version> 
                    <description> 
                         Describes rest calls 
                    </description> 
                  </info> 
                  <templatePath>${basedir}/src/main/resources/strapdown.html.hbs</templatePath> 
                  <outputPath>${project.basedir}/src/main/webapp/swagger.html</outputPath> 
                  <!-- <outputPath>${basedir}/generated/document.html</outputPath> --> 
                  <swaggerDirectory>${project.build.directory}/swagger-ui</swaggerDirectory> 
                  <swaggerApiReader>com.wordnik.swagger.jaxrs.reader.DefaultJaxrsApiReader</swaggerApiReader> 
              </apiSource> 
           </apiSources> 
   </configuration> 
   <executions> 
        <execution> 
        <phase>compile</phase> 
        <goals> 
            <goal>generate</goal> 
        </goals> 
        </execution> 
   </executions>             
</plugin>

The following are few annotations which will be used during swagger documentation:

@Api: Marks a class as a Swagger resource.

@ApiOperation: Describes an operation or typically a HTTP method against a specific path.

@ApiParam: Adds additional meta-data for operation parameters.

Here is a sample example in which a class is marked a swagger resource:

@Path("/user") 
@Api("/user") 
public class UserInformation { 
    UserLoginInfo loginInfo; 
    @Path("/info") 
    @POST 
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED) 
    @Produces(MediaType.TEXT_PLAIN) 
    @ApiOperation(httpMethod = "POST", value = "info", produces = "text/plain") 
    public String login(@FormParam("username") String username, @FormParam("password") String password) { 
        loginInfo = new UserLoginInfo(); 
        String userCredentials = loginInfo.getUserdetails(username, password); 
        if (userCredentials != null) 
            return userCredentials; 
        else 
            return "{\"error\":\"invalid user\"}"; 
    } 
}

Sample swagger documentation looks like:

This way you can document your RESTful web services.  I hope you enjoyed reading this blog post!

I would like to express my gratitude to Mr. Ravi Sangubotla and Mr. Veerabhadra Chary for their constant guidance and support.

 

About The Author

Leave a Reply

*