Integrating Swagger 2 with Spring Boot Applications
Tech
1
Integration Steps
- Add required dependencies to your Maven
pom.xml:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- Create a Swagger configuration class:
@Configuration
@EnableSwagger2
public class SwaggerDocumentationConfig {
private static ApiInfo DEFAULT_META = null;
@Bean
public Docket apiDocket() {
return new Docket(DocumentationType.SWAGGER_2);
}
}
- Access the documentation UI in your browser at:
http://localhost:8080/swagger-ui.html(update the port to match your Spring Boot server configuration)
Custom Configuration
Customize Documentation Page Metadata
Update your configuration class to add custom metadata that displays on the Swagger UI page:
@Configuration
@EnableSwagger2
public class SwaggerDocumentationConfig {
private static ApiInfo DEFAULT_META = null;
@Bean
public Docket apiDocket() {
Docket apiDocket = new Docket(DocumentationType.SWAGGER_2);
ApiInfo apiInfo = new ApiInfoBuilder()
.contact(new Contact(
"Swagger - k8sclient",
"https://github.com/vazquez/k8sclient",
"vazquez@gmail.com")
)
.title("Kubernetes Client API")
.description("This is a simple example of a Spring Boot RESTful service.")
.version("1.0")
.build();
apiDocket.apiInfo(apiInfo);
return apiDocket;
}
}
Reload http://localhost:8080/swagger-ui.html to see your custom changes.
Exclude the Default basic-error-controller
Two common approaches to remove the auto-generated error controller from your documentation listing:
Approach 1: Scan only your controller package
Update your configuration to only scan for APIs in your specified base package:
@Configuration
@EnableSwagger2
public class SwaggerDocumentationConfig {
private static ApiInfo DEFAULT_META = null;
@Bean
public Docket apiDocket() {
Docket apiDocket = new Docket(DocumentationType.SWAGGER_2);
ApiInfo apiInfo = new ApiInfoBuilder()
.title("Kubernetes Client API")
.description("This is a simple example of a Spring Boot RESTful service.")
.version("1.0")
.build();
return apiDocket.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("com.vazquez.k8sclient.controller"))
.build();
}
}
Approach 2: Only include explicitly annotated methods
Configure Swagger to only expose methods that have the @ApiOperation annotation:
@Configuration
@EnableSwagger2
public class SwaggerDocumentationConfig {
private static ApiInfo DEFAULT_META = null;
@Bean
public Docket apiDocket() {
Docket apiDocket = new Docket(DocumentationType.SWAGGER_2);
ApiInfo apiInfo = new ApiInfoBuilder()
.title("Kubernetes Client API")
.description("This is a simple example of a Spring Boot RESTful service.")
.version("1.0")
.build();
return apiDocket.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();
}
}
Add the @ApiOperation annnotation to any controller method you want to display in the documentation (only annotated methods will be visible):
@ApiOperation(value = "Get all events in the target cluster", notes =
