What is Swagger?
Swagger defines a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Swagger UI is a great tool for describing and visualizing RESTful web services. It generates a small webpage, which documents your API and allows you to make test queries using JavaScript. Click here to see a small demo.Swagger integration with Spring boot
application.properties
Configure the required properties for swagger in application.properties file. You can either choose to hardcode these values in "ApplicationConfig.java -> apiInfo()" method. I have pulled them out to have ease of access to these properties.
#------------------Swagger implementation properties------------------
#The title for the spring boot service to be displayed on swagger UI. It will refer to the above value.
swagger.title=Application name
#The description of the spring boot service. It will refer to the above value.
swagger.description=Application Description
#The version of the service. It will refer to the version specified in pom.xml.
swagger.version=@project.version@
#The terms of service url for the service if applicable.
swagger.termsOfServiceUrl=https://www.apache.org/licenses/LICENSE-2.0
#The contact name for the service.
swagger.contact.name=Krishna Kuntala
#The contact url for the service
swagger.contact.url=https://microservices-java.blogspot.co.uk
#The contact email for the service
swagger.contact.email=kuntala.krishna@gmail.com
#The license information about this service
swagger.license=Apache License 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0
ApplicationConfig.java
Add this class in your "ComponentScan" package or subpackages. This class initiates the swagger config for the service.The properties defined in application.properties are mapped to this class.
@Configuration
@EnableSwagger2
public class ApplicationConfig {
/** The title for the spring boot service to be displayed on swagger UI. */
@Value("${swagger.title}")
private String title;
/** The description of the spring boot service. */
@Value("${swagger.description}")
private String description;
/** The version of the service. */
@Value("${swagger.version}")
private String version;
/** The terms of service url for the service if applicable. */
@Value("${swagger.termsOfServiceUrl}")
private String termsOfServiceUrl;
/** The contact name for the service. */
@Value("${swagger.contact.name}")
private String contactName;
/** The contact url for the service. */
@Value("${swagger.contact.url}")
private String contactURL;
/** The contact email for the service. */
@Value("${swagger.contact.email}")
private String contactEmail;
/** The license for the service if applicable. */
@Value("${swagger.license}")
private String license;
/** The license url for the service if applicable. */
@Value("${swagger.licenseUrl}")
private String licenseURL;
/**
* This method will return the Docket API object to swagger which will in turn display the information on the swagger UI.
*
* Refer the URL http://{ip-address or host-name}:{service.port}/{server.contextPath}/swagger-ui.html
*
* service.port and server.contextPath are provided in application.properties.
* If these properties are not defined in the application.properties then the URL for swagger will be
* http://{ip-address or host-name}:8080/swagger-ui.html
*
* @return the docket
*/
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build().apiInfo(apiInfo());
}
/**
* This method will return the API info object to swagger which will in turn display the information on the swagger UI.
*
* @return the API information
*/
private ApiInfo apiInfo() {
return new ApiInfo(title, description, version, termsOfServiceUrl, new Contact(contactName, contactURL, contactEmail), license, licenseURL);
}
}
pom.xml
Add below dependencies in your pom.xml for Swagger.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
Swagger UI
Access Swagger UI using http://{ip-address or host-name}:{service.port}/{server.contextPath}/swagger-ui.html e.g. http://localhost:10020/swagger-ui.html
