XML-Based Swagger 2 Configuration With Spring MVC

Recently, I got a requirement to integrate Swagger 2 with Spring MVC. As the Spring configuration was done using XML based on the project, I had to go for that only, and I started looking for the example but could not find the proper article on the web immediately. Below is the step-by-step guide to configuring Swagger 2 with Spring MVC using an XML-based configuration.

• First of all, add these below dependencies to your pom.xml.

<!--Dependency for swagger 2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>

<!--Dependency for swagger ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>

• Then, find out your MVC dispatcher servlet XML. Sometimes, people name it differently. Specify the base package for the component scan. Note that whatever package you have specified here, the REST services available under this package only will be eligible for Swagger.

<!--Here com.example.service is the base package for swagger configuration -->
<context:component-scan
base-package="com.example.service" use-default-filters="false">
<context:include-filter type="annotation"
expression="org.springframework.stereotype.Controller" />
<context:include-filter type="annotation"
expression="org.springframework.web.bind.annotation.ControllerAdvice" />
</context:component-scan>

• Then declare the bean for Swagger 2 inside the same dispatcher servlet as below.

<bean id="swagger2Config"
class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration">
</bean>

• Then declare the resource mapping for the Swagger UI HTML file and webjars as below.

<mvc:resources order="1" location="/resources/"
mapping="/resources/**" />
<mvc:resources mapping="swagger-ui.html"
location="classpath:/META-INF/resources/" />
<mvc:resources mapping="/webjars/**"
location="classpath:/META-INF/resources/webjars/" />

• Then declare this as the default servlet handler.

<mvc:default-servlet-handler />

Once you are done with the above steps, then your application is configured with Swagger 2. Now, during the deployment, Swagger will automatically find all the resources under the base package and generate the Swagger documentation.

To access your Swagger UI, you need to use the below URL:

http://<Your Host>:<Port>/<Context>/Swagger-ui.html 

Example: http://localhost:8080/ExampleProject/Swagger-ui.html

You can specify your REST APIs with Swagger specific annotation to provide better documentation to your services. For that, you can refer to the official Swagger core annotation page.

If you are using Spring Boot, then Swagger 2 configuration is very easy. There are lots of articles on the web for annotation-based Swagger configuration. One of them you can refer to is Setting Up Swagger 2 with a Spring REST API.

If you want to configure Swagger 2 with your XML based existing Spring application without changing any Java code, then I hope this helped!