How to Use Spring Fox in Java Application Development

By | August 13, 2016

In this blog post, java application development professionals have explained the concept of Spring Fox framework. They have explained its uses and advantages in this post. Read the article to know more about Spring Fox.

Technology: Spring Fox is the framework for Java which will automate the human/machine readable specification for JSON Restful API.

It scans all spring beans and it generates the HTML page based on spring based web application configuration. It is generated from source code, we can guarantee that documentation for Rest API will be sync with latest implementation.

Pre-requisites:
Swagger is the Java API which will provides the annotations to generate easily testable HTML page for RESTful web applications.

Swagger is the Specification for our Restful API.it provides all the application endpoints and also provides a way how to call endpoints, what are the parameters are required, and also it provides response format of the endpoint. The method, parameters and request/response models will be synchronization with code.

Advantages of Swagger: Rest API can easily understand the Rest API, and they can easily consume the Rest API without having any prior knowledge on Rest API producer. The Swagger UI framework allows both producers and users to interact with the API. It gives clear insight into how the API responds to parameters and options.

Spring Fox is the framework on top of Swagger API and integrating with Spring framework. Spring Fox will provides the annotations which will bootstrap the swagger framework.

Adding Maven Dependency:

Some of Useful annotations provided by Swagger:

  1. @ API: It is the core annotation for Swagger API, if any of the class annonated with this Swagger will treat this as a resource. It is used to introspect by swagger core for generating documentation.
  2. @ApiImplicitParam: It is used to inform the swagger core as Request Parameter, using this we can specify the attributes.
      • name : request parameter name that we are expecting
      • dataType: what type of the object we are expecting.
      • required: request parameter is needed compulsory to process the request or it is the optional parameter.
      • defaultValue: If it is the optional parameter any default value we want to set it.
      • allowableValues: What are the different value that the parameter can accept.
      • allowMultiple: The parameter can accept the multiple values or it can only accept the single value.
      • paramType : Type of the parameter, parameter will be as part of the request URL, or it is the path parameter or it will be present in the request body.
      • Example: We can provide the example using @Example annotation.
  3. @ApiImplicitParams: It is the annotations to specify the multiple parameters for an REST endpoint.
  4. @ApiModel:It is the annotation used for Requestbody and Response, it is used to provide the how the requestbody we need to send the server, it provides the sample content.
  5. @ApiOperation: It is used specify the what type of the request method we are using for the endpoint like GET,POST, PUT or DELETE etc…
  6. @ApiResponse: It is used to specify the what kind of the response we will get from producer. Eg: @ApiResponse(code = 200, message = “Job info”, response = JobDetails.class)
  7. @ApiResponses : It is used to specify the what are the different types of the responses we will get from Producer Rest API.
  8. @ResponseHeader: It is used to specify the what are the different header producer is expecting.
    • Producer can also specify the name header field.
    • Type of the header value.
    • Description: purpose of this header.
    • reponseContainer: if it the collection type, what type the collection like List or Set.
  9. @Tag: we can also tag the endpoint using this annotation.

Sprig fox is provided some more annotations on top of the swagger annotations:

@EnableSwagger2: It indicates that swagger support is enabled, it must annonated along with Spring configuration annotation so that it will scan all spring beans to provide the documentation.

Some of the Core API`s provided by Spring Fox:

ApiInfo: it is the one of the core API, which is used show the API related information like What is the API, API overview, what is the use and some description about API, and it also provide the LICENCE information if present.

ApiInfoBuilder is the builder class to create the ApiInfo class.

Docket: A builder which is intended to be the primary interface into the swagger-springmvc framework. Provides sensible defaults and convenience methods for configuration.

Where we specify the package to scan and creating documentation.

Here we are not limiting the Spring Fox to scan a package.

We need to mark these (Docket, ApiInfo) classes as spring beans.

If we run the spring application swagger ui will look like this:
Swagger UI

The listed entries are the Spring MVC controllers.

If we can expand the any of the controller it will show what are the different endpoints that controller is producing.

Controller Endpoint

The above are the endpoints provided by TaskController controller class.

If we can expand the any of the endpoint it will show what are the parameters are required by endpoint.

Endpoint Parameters

Model will show the content how response will look like.

Status codes are the possible error/success codes that service can send to the client. We can share this HTML page to the consumer of the service so that they can understand how the service will look like.

If the endpoint is POST request type, it will also show the sample body how we need to pass the request body.

API Tasks

We can also test our rest endpoints using Swagger-UI .we can pass the required parameters and we can click on “Try it out” it will call the service and it will show the response.

REST Endpoint using Swagger-UI

After integrating all required changes of spring Fox to the spring application the one of the configuration will look like:

Sample code to Download:
https://github.com/sravan4rmhyd/spring-boot-axon-sample.git

After deploying the application URL to get swagger UI is:
http://localhost:8080/swagger-ui.html

It also generate the JSON document using that we can enhance/design the applications using Swagger-Editor.

URL to get the JSON file:
http://localhost:8080/v2/api-docs

Download the JSON file, and open http://editor.swagger.io/ and we can paste the downloaded JSON to share the design document of the project.

Java E-Commerce Store

Spring Fox framework is for java application development community people. You can share more details related to Spring Fox that are not available in this post. Feel free to feedback and share your thoughts with our other readers.

Spring Fox Framework

Conclusion:
Spring Fox is the framework on Swagger for spring based applications. It will generate the Rest API documentation for all spring based applications.

Author Bio:
James warner is senior java application development. He works as a developers in NexSoftSys. He major contribute included the collection web services and Java framework. He is extensive experience as java technology and object oriented programming language. You can follow me on twitter @nexsoftsys and you can add circle on Google+.


Java Application Development Jobs

[php snippet=8]