Configuration of Spring Boot with JAX-RS producing OpenAPI 3.0 specification
You can use Swagger to generate an OpenAPI 3.0 together with Spring Boot and JAX-RS by doing the following:
- Include
spring-boot-starter-jersey, swagger-core, swagger-annotations and swagger-jaxrs in pom.xml
- Extend
ResourceConfig and configure the packages to scan for JAX-RS annotations and register the OpenAPIResource.class of Swagger.
- Use Swagger Annotations to annotate your endpoints and your schema.
- Optionally include
sprindoc-openapi-ui if you want to access Swagger via /swagger-ui.html.
1) Dependencies in pom.xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jersey</artifactId>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-core</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-jaxrs2</artifactId>
<version>${swagger.version}</version>
<exclusions>
<exclusion>
<groupId>io.github.classgraph</groupId>
<artifactId>classgraph</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.2.18</version>
</dependency>
Current swagger-version is 2.1.0.
There is a conflict with springdoc-openapi-ui and swagger-jaxrs2, which leads to an error with io.github.classgraph so this library must be excluded from swagger-jaxrs2.
2: Extending ResourceConfig
@Component
@ApplicationPath("/api")
@Path("/")
public class JaxRsConfig extends ResourceConfig {
public JaxRsConfig() {
// register resources
packages("com.example.jaxrs.resources");
register(OpenApiResource.class);
}
}
The JAX-RS annotated resources must be scanned by calling packages("com.example.jaxrs.resources").
Be careful, not to confuse with the register function!
The OpenApiResource.class comes from Swagger and offers the /openapi.json endpoint.
The reason why I use /api as @ApplicationPath is, that when using it together with springdoc-openapi-ui, the swagger-ui.html endpoint is not found when the @ApplicationPath is set to "/". It seems that something is getting overwritten in this case. Maybe someone has an explanation for this.
3) Swagger Annotations
@Schema(name = "Message", description = "This is an object to place a message.")
public class MessageDto {
@Schema(name="Message", required = true)
private String message;
public MessageDto(String message) {
super();
this.message = message;
}
// ... getters and setters
}
4) Configuring SpringDoc
By default, you should be able to call /swagger-ui.html to open Swagger and browse your OpenAPI 3.0 definition.
Since the @ApplicationPath is set to /api, we need to configure SpringDoc where to look for the definition by setting a property in application.properties:
springdoc.api-docs.path=/api/openapi.json
You can also change the URL of Swagger with:
springdoc.swagger-ui.path=/swagger-ui.html
Other issues:
Another issue may arise, when running the application as a .jar file:
Spring boot application won't run when trying to run from the jar file
In this case I've found a solution by scanning all the components with a reflection library like org.reflections like so:
private void scan(String... packages) {
for (String packageName : packages) {
Reflections reflections = new Reflections(packageName);
reflections.getTypesAnnotatedWith(Provider.class).parallelStream().forEach(clazz -> register(clazz));
reflections.getTypesAnnotatedWith(Path.class).parallelStream().forEach(clazz -> register(clazz));
}
}
