Swagger – API Documentation

 

A Bit of Theory

First of all, it is vital to explain what Swagger actually is. Generally, we can define it as a tool that automatically creates API documentation.

While working on big-scale projects developing web applications, that are often linked with AS, it is sometimes hard to find our way around the offered services. It is often due to the fact that documentation or the description of the context in which they should be used is missing. In such cases, we could consult our co-workers or contact the competent people. However, sometimes we end up figuring it out ourselves by debugging a given service, which takes a lot of time. Given a complete API specification, for instance in a web application, the time we spent on that investigation, could be better used on implementation. Swagger provides such functionality, at a relatively low cost. I’m obviously referring to Swagger UI app, that provides a full API specification and is available online.

In the following part of this article, I am going to elaborate on the way Swagger can be used in an application – from the configuration in Spring, to the generation of classes based on JSON file, in which API definition is located. I will conclude by saying a few words about Swagger UI app.

Why Should You Use Swagger?

At the beginning of this article, we learnt about the main advantage of Swagger – the access to the API documentation. However, it is also significant to mention other benefits of using this framework, that include:

●     frontend and backend teams can work simultaneously

●     frontend doesn’t need to know the method of server implementation

●     Swagger UI gives a possibility to view a whole API

●     generating API based on JSON or YAML file

●     API testing

●     Swagger supports a lot of frameworks and programing languages

 

Given the API specification in JSON file, we get access to the definitions of services – which include the information about entry and output parameters, the type of the service (GET or POST) etc. Therefore, the teams that are responsible for the development of frontend and backend can work independently of each other. For the frontend team, backend implementation is transparent – they only need to know the entry and output parameters. An additional benefit is that the two teams can work simultaneously which saves a lot of time.

Swagger Configuration

Spring Configuration

Enough with the theory – let’s look at some parts of the actual code:

 

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
 
@Path("/user")
@Api(value = "/user", description = "User REST for Integration Testing")
public interface UserService {
 
    @GET
    @Path("/getUser/{username}")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    @ApiOperation(value = "Get user details", response = User.class)
    public User getUser(@PathParam("username") String username);
 
    @POST
    @Path("/saveUser")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    @ApiOperation(value = "Save user details", response = User.class)
    public User getUser(User user);
}

In this case, it is vital to notice the annotation. Let’s focus on @Api and @ApiOperation, that come from Swagger package. It is because of those tags that Swagger is able to generate the documentation while scanning our packages. @Api is the description of the set of services, and @ApiOperation contains the description of a particular service. The second annotation also reveals an output class.

 

After describing a whole API, the next step it choosing which packages Swagger has to scan.

<bean id="swaggerConfig" class="com.wordnik.swagger.jaxrs.config.BeanConfig">
        <property name="resourcePackage" value="com.project" />
        <property name="version" value="2.0" />
        <property name="basePath" value="http://localhost:8080/SwaggerUI-Integration/rest" />
        <property name="title" value="Swagger UI Integration Sample" />
        <property name="description"
            value="Swagger UI Integration Sample for demonstrating its working." />
        <property name="contact" value="contact@projects.com" />
        <property name="scan" value="true" />
</bean>

Then we need to download Swagger UI app and add it to our package.

The steps described above are sufficient to generate a full documentation and to view it on Swagger UI app.

Swagger-codegen

At this point, I would like to present how to generate API – the REST Controllers and the model. It requires Maven and an appropriate plugin.

We need to start with pom.xml and add:

<build>
	<plugins>
		<plugin>
    		<groupId>io.swagger</groupId>
    		<artifactId>swagger-codegen-maven-plugin</artifactId>
    		<version>2.2.1</version>
     		<executions>
        		<execution>
            		<id>sampleId</id>
            		<goals>
                		<goal>generate</goal>
                	</goals>
			<configuration>                                   
			<inputSpec>${project.basedir}/swagger-api/sample.json</inputSpec>
                	<templateDirectory>${project.basedir}/templates</templateDirectory>
                 		<output>${project.basedir}</output>
                		<apiPackage>com.sample.api</apiPackage>
                		<modelPackage>com.sample.model</modelPackage>
                		<environmentVariables>
                        	<apis />
                        	<models />
                    	</environmentVariables>
                	</configuration>
            	</execution>
      		</executions>
    	</plugin>
	</plugins>
</build>

Let’s move on to the configuration section. As inputSpec we provide a JSON file, based on which Swagger generates controllers and the model, that will be later used to communicate with AS. Here we also give the names for the packages of generated classes. The most interesting tag in this section is templateDirectory. At this point, we need to define the path to template, which determines the form of generated API classes, using Mustache API.

With this configuration, every time we launch mvn clean install a whole API will be generated based on a given JSON file.

Class generation can also occur without Maven and template. In such case, we need to download swagger-codegen-cli app. Below you can see an example of this approach:

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate  
     -i http://petstore.swagger.io/v2/swagger.json  
     -l java  
     -o samples/server/petstore/java

Swagger UI

Once we generated the API, we can view the service through a web application. In order to do that, we have to download Swagger UI app and deploy it, for instance on tomcat. API specification in the form of JSON file should be attached to the application.

b1

In the print screen above, we can see the service specification, mentioned at the beginning of the article. It clearly shows which parameters are the arguments for the given service and with which class it answers. We can also test the performance of the service, which requires an app working on a chosen server.

I strongly recommend testing Swagger UI App, that is available online. Once you use the option of saving and downloading you will realize how convenient it is to test API with the Swagger.

Extension

It is also vital to think about an extension of the solution that I have presented. The nest step could be the simulator configuration that answers with sample data. Such simulator can be based on nodejs server.

 

mm

Bartek Bąba

Senior Software Developer

You may also like

Leave a comment

one × 2 =