Documenting Spring APIs Using OpenAPI 3

Documentation is one of the most important things when it comes to developing an application. There are so many APIs with poor or even no documentation, but it doesn’t have to be like that. Documenting our APIs should be a thing we always do because without it nobody knows how to use our application and that is probably something that we want to avoid.
That’s why in this article I’ll show you how documenting Spring APIs using OpenAPi 3.0 can be straightforward.

Dependencies

Add the following dependency:

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
	<version>2.2.0</version>
</dependency>

Generated URLS

This library will automatically configure itself and will generate two new urls:

http://localhost:8080/swagger-ui/index.html

http://localhost:8080/v3/api-docs

If we try to access the first url well’get the following page:

The above page is the place where we share the documentation about our APIs. It’s totally dynamic and every change we do to our APIs will be later rendered in this page. At the moment we haven’t created any controller, that’s why we see “No operations defined in spec!”.

The other url is also available on this page by clicking /v3/api-docs. It will redirect you to the same page but this time in JSON format, which is really useful if you want to share your documentation.

Customizing OpenAPI Info

We can customize almost every aspect of our documentation, like title, description and so on.

@Configuration
public class OpenApiConfig {

	@Bean
	public OpenAPI customOpenAPI() {
		return new OpenAPI().components(new Components()).info(new Info().title("Spring Open API example")
				.description("A simple example about using Spring and Open API").version("1.0.0"));
	}

}

Restart the app and reload the page to see the changes.

Defining a Simple API

Let’s create a simple API to manage users:

@RestController
@RequestMapping("/users")
@Tag(name = "Users")
public class UserController {

	@GetMapping
	@Operation(summary = "Get all users")
	public ResponseEntity<List<User>> findAll() {
		return ResponseEntity.ok(List.of());
	}

	@GetMapping("/{id}")
	@Operation(summary = "Get a user by id")
	public ResponseEntity<User> findById(@PathVariable int id) {
		return ResponseEntity.ok(new User());
	}

	@PostMapping
	@Operation(summary = "Insert a user")
	public ResponseEntity<User> insert(@RequestBody User user) {
		return ResponseEntity.ok(user);
	}

	@PutMapping("/{id}")
	@Operation(summary = "Update a user")
	public ResponseEntity<User> update(@PathVariable int id, @RequestBody User user) {
		return ResponseEntity.ok(user);
	}

	@DeleteMapping("/{id}")
	@Operation(summary = "Delete a user by id")
	public ResponseEntity<Object> delete(@PathVariable int id) {
		return ResponseEntity.noContent().build();
	}

}

In this example we’re using @Tag to document the entire controller, and the @Operation annotation to document a specific endpoint. Now if we try to access the page again we’ll be able to view the operations:

Let’s now open the first endpoint to see the details:

In this section we can see the request parameters, the responses and we can even try to hit the endpoint.

Validation

At the bottom of th page you’ll find the schemas used in the endpoints. If we want to add validation to them, all we need to do is adding JSR-303 annotations and the UI will display the constraints.

Conclusion

In this article we have seen how documenting Spring APIs using OpenAPi 3.0 can be straightforward and and how this process is totally automated. Creating documentation is never an easy task to do but thanks to tools like SpringDoc our job is easier and we can spend more time focusing on other tasks.
The source code of this project is available on GitHub.