{{announcement.body}}
{{announcement.title}}

OpenAPI (Swagger) and Spring Boot Integration

DZone 's Guide to

OpenAPI (Swagger) and Spring Boot Integration

In this article, take a look at OpenAPI (Swagger) and Spring Boot integration.

· Integration Zone ·
Free Resource

Laptop with code on screen

Recently. while working on a requirement, there came a need to upload a file for further processing. Mostly in REST APIs, we are accustomed to using JSON input and output while it is XML for SOAP web services. 

This leads us to research how to satisfy the requirement. In Spring, and mainly in Spring Boot, the auto-configuration feature gives us big-time help even though sometimes we have to disable some features to add custom once or to change the order they are sorted in.

The @Order annotation defines the sorting order of an annotated component or bean. It has an optional value argument that determines the order of the component. The default value is Ordered.LOWEST_PRECEDENCE. This marks that the component has the lowest priority among all other similar components. 

In this article, I will describe how we can integrate OpenAPI (Swagger) specification to a spring boot project, particularly focusing on handling multipart/form-data. In the demo app, we will try to upload a document, particularly an avatar for a user account. We are going to use  MultipartResolver, particularly CommonsMultipartResolver for an added advantage. There is no default resolver implementation used for Spring DispatcherServlets, as an application might choose to parse its multipart requests itself. To define an implementation, create a bean with the id "multipartResolver" in a DispatcherServlet's application context. Such a resolver gets applied to all requests handled by the DispatcherServlet

You might also like:  Spring Boot 2 RESTful API Documentation With Swagger 2 Tutorial

As it has been mentioned in the documentation, there are two concrete implementations included in Spring, as of Spring 3.1:  

To use CommonsMultipartResolver to handle the file upload, we need to add the following dependency:

XML


And define CommonsMultipartResolver  bean:

Java


StandardServletMultipartResolver for the Servlet 3.0+ Part API   

For more flexibility and configurability, I choose to use CommonsMultipartResolver. Among the advantages, it provides "maxUploadSize", "maxInMemorySize", and "defaultEncoding" settings as bean properties.

Let’s get practical:

  1. Create swagger definition 

  2. Create the Spring Boot Project (I will follow 3 tier model)

  3. Define Database configurations and entity classes

  4. Create JPA Data Repository layer

  5. Create Services and Rest Controllers

  6. Build and run the Project

Tools and Technologies Used

  1. Eclipse (you can use your preferred editor) 

  2. Swagger editor (https://editor.swagger.io/) — Swagger - 2.0

  3. Spring Boot — 2.0.4.RELEASE, Spring Data Jpa (https://thoughts-on-java.org/what-is-spring-data-jpa-and-why-should-you-use-it/)

  4. JDK — 1.8 or later 

  5. Maven

Audience: It is expected that you have a basic understanding of Spring Boot.

Step 1: Why Swagger, You May Ask? 

Earlier, there were no industry standards for developing APIs or documenting them. Swagger emerged as an approach to building APIs and soon became the most popular framework for this purpose. Swagger is the largest framework for designing APIs using a common language and enabling the development across the whole API lifecycle, including documentation, design, testing, and deployment. The framework provides a set of tools that help programmers generate client or server code and many more. For more details, I recommend checking out swagger.io

I have created a minimal definition that serves enough for this post. Please refer to the definition file included in the project. I will not go in details of how to define Swagger specs. For details, I recommend referring to https://swagger.io/.

The following are the endpoints for our demo app:

  • Create a user(avatar should be updated later)

  • Get user information by user id

  • Update avatar image (uses multipart/form-data)

Step 2: Create and Import Project

Let's create and import our application in your favorite IDE. There are many ways to create a Spring Boot application, the simplest way is to use Spring Initializr http://start.spring.io/.

You can also import the sample project from here.

Step 3: Define Database Configurations and Entity Classes

There is a single entity for which we will be adding user-name and avatar image. For my convenience, the avatar will only be a string reference to the location/path on the server where the files are located (can also be saved in a database column).

Java


And persistence config (the code is self-explanatory):

Java



Step 4: Create Repository 

Spring Data makes it very easy to work with entities by merely defining repository interfaces. It takes the domain class to manage as well as the id type of the domain class as type arguments. It comes with a set of predefined methods and allows for the possibility of adding custom methods in each interface, which we will not cover in this post. 

Java

 

Step 5: Create Services and Rest Controllers

I won’t go into describing how to create services and controllers since I assume that you have enough knowledge.

Let’s put all together and check what we have done so far. 

  • Run the project with: mvn clean spring-boot:run

  • From postman (or other tools), try to call “http://localhost:8080/v1/user” as the following. You should see resultCode = 200 if everything goes as expected.

  • Update avatar:

  • Check if it has been saved:


Note: Don’t forget to create a folder named  “images” or name it how you like in application.yaml.

You can get the complete example from GitHub.

Thank for following this to the end :)

Further Reading

Swagger Generation With Spring Boot

Spring Boot and Swagger: Documenting RESTful Services

Topics:
spring swagger ,spring boot ,multipartfile ,integration ,tutorial ,openapi

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}