Springfox
External
- http://springfox.github.io/springfox/
- http://springfox.github.io/springfox/docs/current/
- https://github.com/springfox/springfox
Internal
Overview
Springfox is a suite of Java libraries for automating the generation of machine and human readable specification for JSON APIs written with Spring Framework. Springfox works by examining an application, once, at runtime to infer API semantics based on Spring configurations, class structure and various compile time java annotations.
Dependencies
repositories {
jcenter()
}
dependencies {
implementation "io.springfox:springfox-swagger2:2.9.2"
}
Essential Classes
Docket
springfox.documentation.spring.web.plugins.Docket: the primary API configuration mechanism.
ApiSelectorBuilder
ApiSelectorBuilder provides fine grained control over the endpoints exposed via swagger.
Annotations
Security Schemas
The following security schemas are available to protect the API:
- ApiKey
- BasicAuth
- OAuth
Models
Non-reachable Model
A model that should be described in the generated specification but is not explicitly used in any operation.
Generating Swagger/OpenAPI Specification from Spring Code with Springfox
External
- https://springframework.guru/spring-boot-restful-api-documentation-with-swagger-2/
- http://springfox.github.io/springfox/docs/current/
- https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
Playground Example
General Considerations
This section shows how to dynamically generate a Swagger 2.0 specification of the implemented API at runtime, as JSON. The second part of the section shows how to enable UI support for browsing the API specification.
Generating the Swagger Specification
At this point, only the "io.springfox:springfox-swagger2" dependency is needed. This dependency contains all the functionality Springfox needs to generate the specification of the API, in JSON format, at runtime.
There are two essential code changes:
1. Annotate the Spring Boot application class, or a Configuration with @EnableSwagger2. It is preferable to provide a separated Configuration class, dedicated to Swagger.
2. Expose a configured Docket instance as a bean:
@Configuration
@EnableSwagger2
public class SwaggerConfiguration extends WebMvcConfigurationSupport {
// ...
@Bean
public Docket swaggerSpecification() {
Docket docket = new Docket(DocumentationType.SWAGGER_2);
// ApiSelectorBuilder gives fine grained control over the endpoints exposed via swagger
ApiSelectorBuilder apiSelectorBuilder = docket.select();
apiSelectorBuilder.
apis(RequestHandlerSelectors.any()).
paths(PathSelectors.any()).
build();
// adds a servlet path mapping, when the servlet has a path mapping. This prefixes paths with the provided path mapping
docket.
pathMapping("/").
tags(new Tag("A Service", "All APIs relating to A"));
return docket;
}
If these two elements are present, the Spring application will generate its JSON-formatted. Swagger2 specification while invoked as: http://localhost:8080/v2/api-docs
For a complete example see SwaggerConfiguration.java.
UI Support
UI Support Dependency
dependencies {
implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}
Code Changes
Spring Boot should auto-configure Springfox UI support, but for some reason it didn't last time I tried. The following resource handlers were added explicitly in the code, as part of a class that extends WebMvcConfigurerAdapter, and is annotated with @EnableWebMvc:
@Configuration
@EnableSwagger2
public class SwaggerConfiguration extends WebMvcConfigurationSupport {
// ...
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
UI Access
The UI is accessible at http://localhost:8080/swagger-ui.html