Swagger with Spring REST API
REST is the ultimate way to expose web services nowadays. But, how do state to clients and how to use a REST API? There’s no real standard or at a minimum de facto standard to expose a REST contract. Many API spots human-readable documentation, which is currently edited and thus hard to keep perfectly synchronized with the API. Another process is to generate the documentation from the code itself, and this is what this article covers, by using Swagger on top of Spring MVC.
Swagger
Swagger is a specification for documenting REST API. It identifies the format (URL, method, and representation) to describe REST web services. It delivers tools to generate/compute the documentation from application code also.
What can be its mean? As an application developer, you write web services and operate your preferred framework, Swagger scans your code and exposes the documentation on some URL. Any client can absorb this URL (which comes as XML or JSON documents) and learn how to use your REST web services: which HTTP technique to call on which URL, which input documents to deliver, which status code to expect, etc.
We’re going to see how to use Swagger on top of Spring MVC, but remember Swagger is a specification and supports a wide range of frameworks.
The controller
The controller holds the basic CRUD operations, it utilizes the Spring MVC API:
@RestController
@RequestMapping("/user")
@Api(value = "api/v1",tags = "USER REST CONTROLLER")
public class UserController {
ConcurrentHashMap<Integer, User> users = new ConcurrentHashMap<>();
@GetMapping("/{id}")
public User getUser(@PathVariable int id){
return users.get(id);
}
@GetMapping("/getAllUser")
public List<User> getAllUser(){
return new ArrayList<User>(users.values());
}
@ApiResponses(value = {
@ApiResponse(code = 200,message = "OK"),
@ApiResponse(code = 401,message = "Unauthorized User"),
@ApiResponse(code = 403,message = "Forbidden User")
})
@PostMapping("/addUser")
public User addUser(@RequestBody User user){
users.put(user.getId(), user);
return user;
}
}I create the controller as simply as possible, the point isn’t to have a perfect, indestructible controller, but rather to illustrate the use of Swagger.
Swagger configuration
A nice and active project on GitHub provides Swagger support for Spring MVC REST API. The XML configuration is straightforward:
@Configuration
public class SpringFoxConfiguration {
@Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// .apis(RequestHandlerSelectors.any())
.apis(Predicate.not(RequestHandlerSelectors
.basePackage("org.springframework.boot")))
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("AIP FOR SWAGGER")
.description("THIS IS MY REST API")
.version("0.0.1-SNAPSHOT")
.build();
}
}
Swagger Spring MVC requires a few properties from a property file:
spring.mvc.pathmatch.matching-strategy = ANT_PATH_MATCHER
server.port = 8080We’ll see shortly how Swagger Spring MVC utilizes these 2 properties.
What’s occurring under the hood? Swagger Spring MVC scans the Spring MVC controllers on initiate and registers a documentation controller. It exposes the operations the controllers permit. This document follows the Swagger specification: any client that acknowledges this specification can use the API. The good news is the documentation is established on the code itself: any change to the code is reflected on the documentation, no need to maintain an external document.
Swagger Spring MVC uses Spring MVC annotations to figure out the documentation, but it also understands Swagger annotations. Let’s put on the @Api annotation on the controller:
@RestController
@RequestMapping("/user")
@Api(value = "api/v1",tags = "USER REST CONTROLLER")
public class UserController { ... }It’s time now to discover the documentation.
Swagger documentation with REST API
Here is the documentation endpoint on the /api-docs URL, if we hit this URL and ask for JSON content, we’ll get the following snapshot:-
{
"swagger":"2.0",
"info":{"description":"THIS IS MY REST API"
"version":"0.0.1-SNAPSHOT",
"title":"API FOR SWAGGER"},
"host":"localhost:8080",
"basePath":"/",
"tags":[{"name":"basic-error-controller",
"description":"Basic Error Controller"
}
]
}
Remember that, we pitch on the 2 properties we set up previously, the version of our API and the base path of the API. Both will appear on each page of our documentation.
If we want to work on the users, we just have to follow the link to find out more about the exposed operations on this resource. Hence, let’s hit /api-docs/users, here is an excerpt of the result:-
{
"swagger":"2.0",
"info":{"description":"THIS IS MY REST API",
"version":"0.0.1-SNAPSHOT",
"title":"API FOR SWAGGER"},
"host":"localhost:8080",
"basePath":"/",
"tags":[{"name":"user-controller",
"description":"User Controller"}],
"paths":{"/user/addUser":{"post":{"tags":["user-controller"],
"summary":"addUser",
"operationId":"addUserUsingPOST",
"consumes":["application/json"],"produces":["*/*"],
"parameters":
[
{
"in":"body",
"name":"user",
"description":
"user",
"required":true,
"schema":properties":
{
"id":
{
"type":"integer",
"format":"int32"},
"name":{"type":"string"},
"phone":{"type":"integer",
"format":"int64"}
},
"title":"User"
}
}
}Here, there are two parts to this documentation:- That is the operations and the models. A client can send a GET on the /user URL to select the users. This can be an example of an operation. We can see this operation returns a collection of users. A client can pursue more about this model in the models segment. Note the User model, which is used by the GET and POST operations (not shown above). All of these operations are scanned from the controller.
As much, so good: I write a controller and get its documentation for free. But this is only the start: let’s see now how to ruin this documentation, first from a programmatic client, and second from a neat user interface.
This time, refer back to the next JSON document to acknowledge what the client is doing. It basically searches the path of an operation whose nickname is sort and ensures this operation is exposed on a GET operation. Once it has the path, it delivers the request and gets the following rep from one, of the users:
[
{
"id": 1,
"firstname": "Deepak",
"lastname": "Kumar"
},
{
"id": 2,
"firstname": "Krishna",
"lastname": "Vasudev"
},
{
"id": 3,
"firstname": "Versha",
"lastname": "Limbachia"
},
{
"id": 4,
"firstname": "Harsha",
"lastname": "Bhogle"
}
]
It is not that much great? With only the documentation URL as an entry point and a little similar idea about what it wants to do, the client can find a suitable request to make. If we redesign the controller, the client shouldn’t break, as long as it follows the documentation. That is nice decoupling.
Swagger UI with REST API
Have you ever used written-by-hand web service documentation which isn’t up-to-date? I believe we all are intimate with that. The API developers are busy writing the APIs, they don’t have more time or forget to upgrade the documentation, and the API client developers are trying to figure out how to operate the API, but the documentation is snap or obsolete. No one is happy with it.
Imagine now the developers that write client applications can consult a beautiful UI that tells them how to use the API. The UI even identify them with what kind of documents the API expects. This UI exists and is called Swagger UI:
Swagger UI just anticipates a URL that leads to Swagger-compliant documentation. It then uses the documentation to present all the operations.
Swagger UI also audits the models, so finding out about the structure of the JSON documents the API expects is elementary. Below is an example of the PUT operation:
Also, Swagger UI lets you try out operations and see the outcomes.
References
- https://swagger.io/blog/api-development/getting-started-with-swagger-i-what-is-swagger/
- https://swagger.io/tools/swagger-ui/
Conclusion
Now, time to wrap up. I hope you’re satisfied tools like Swagger are the way to go to build real REST API and get all the benefits this architecture style promises. Don’t wait any longer and check how to involve Swagger in your project, as it has out-of-the-box support for numerous REST frameworks (JAX-RS/Spring MVC for Java, Django for Python, etc).
