OAS3 AND SPRING BOOT 

Looking for an easy way to document your Spring Boot API following the OAS3 specification? Use a Springdoc documentation endpoint, for OAS3 and Spring Boot! In this post we set up Springdoc and add documentation to an example endpoint.

The code for the Springdoc project can be found on github here and some more documentation and examples can be found here.

We will add OAS3 documentation to a Java Spring API from a previous post on Kubernetes Helm. The completed code for this post is found on github here.

Setup Springdoc

To setup Springdoc we only need to add the following dependency.

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.2.30/version>
</dependency>

When we build and run our API we get the current documentation from the following endpoint.

NOTE: I’m using httpie to do HTTP calls from the terminal. Read more about it in a previous post on httpie.

And if you prefer documentation in yaml format you can do the following.

Configure

We can customise the behaviour of this endpoint with application properties. All are prefixed with springdoc.

springdoc.api-docs.path=/documentation

The above property sets the path of the documentation endpoint. We can also filter to include endpoints in our documentation by package:

springdoc.packagesToScan=nl.sybrenbolandit.greetings

Or by path:

springdoc.pathsToMatch=/v1, /api/person/**

Apart from the OAS3 documentation endpoint Springdoc provides a swagger ui for our API. It’s available on http://localhost:8080/swagger-ui/index.html.

But we can disable this functionality with the next property.

springdoc.swagger-ui.enabled=false

With these properties we can configure Springdoc but we still have an empty documentation for our API. In the next section we will get you started.

Document your endpoints!

First of all you need some general documentation for the whole API. I chose to place this on the Application class. Here we specify the title and the version of our API using the OpenAPIDefinition annotation.

@OpenAPIDefinition(info = @Info(
    title = "Java Spring API", 
    version = "1.0.0"))
@SpringBootApplication
public class SpringApiApplication { ... }

Next you can use the Operation annotation on every endpoint to add a description. Another feature is tags, on which the endpoints can be grouped together.

@GetMapping("")
@Operation(tags = "Person", description = "Get a greeting")
public String greeting(@RequestParam(value="name", defaultValue = 
    "you") String name) { ... }

The rest of documentation is generated out of the annotations you already used. Here is the output of what we created until now.

Hopefully you can now get a OAS3 documented API with Springdoc in no-time! Happy doc-ing!