Generating Swagger documentation with SpringDoc
In this tutorial, I will explain how to generate Swagger OpenAPI v3 documentation for Spring microservices using SpringDoc.
Prerequisites
To follow this tutorial, you should have the following prerequisites:
- Basic knowledge of Spring Boot and RESTful Web Services.
- A basic understanding of OpenAPI specification and how it works.
- A basic understanding of Maven or Gradle build systems.
- JDK 11 or later installed on your machine.
What is springdoc?
Springdoc is an open-source library that enables auto-generation of OpenAPI v3 documentation for Spring Boot RESTful Web Services. It is built on top of the Spring Framework and uses annotations to generate the documentation.
Setting up the Project
To start, let’s create a new Spring Boot project using the Spring Initializr. You can do this by going to https://start.spring.io/ and selecting the following options:
- Project type: Maven or Gradle
- Language: Java
- Spring Boot version: 2.5.0 (or the latest version available at the time)
- Project metadata: Enter a Group and Artifact name, and select the packaging type as JAR.
Once you have selected these options, click on the “Generate” button to download the project zip file. Extract the contents of the zip file to a directory on your machine.
Adding Dependencies
To use SpringDoc, we need to add some dependencies to our project. These dependencies include:
- springdoc-openapi-core: This is the core library that provides the functionality to generate OpenAPI documentation.
- springdoc-openapi-ui: This is a UI library that provides an HTML user interface for the OpenAPI documentation.
If you are using Maven, add the following dependencies to your pom.xml file:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-core</artifactId> <version>1.5.5</version> </dependency> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.5.5</version> </dependency> |
If you are using Gradle, add the following dependencies to your build.gradle file:
|
1 2 3 4 5 |
implementation 'org.springdoc:springdoc-openapi-core:1.5.5' implementation 'org.springdoc:springdoc-openapi-ui:1.5.5' |
Enabling Springdoc
To enable springdoc, we need to add some annotations to our Spring Boot application. First, add the @EnableOpenApi annotation to the main Spring Boot application class. This annotation enables the automatic generation of OpenAPI documentation:
|
1 2 3 4 5 6 7 8 9 10 |
@SpringBootApplication @EnableOpenApi public class MyApplication { public static void main(String[] args) { SpringApplication.run(MyApplication.class, args); } } |
Next, we need to add some annotations to our RESTful API endpoints. These annotations provide additional information about the API, which springdoc uses to generate the documentation. For example, we can use the @Operation annotation to provide a description of the API operation, and the @Parameter annotation to provide information about the input parameters:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
@RestController public class MyController { @GetMapping("/hello") @Operation(summary = "Say hello") public String hello( @RequestParam(name = "name", defaultValue = "World") @Parameter(description = "Name to say hello to") String name) { return "Hello, " + name + "!"; } } |
In this example, we have added the @Operation annotation to the hello() method to provide a summary of what the API does and added the @Parameter annotation to the name parameter to provide additional information about the input parameter.
Accessing the OpenAPI Documentation
Once we have added the necessary annotations, we can access the OpenAPI documentation by visiting the following URL in a web browser:
|
1 2 3 |
http://localhost:8080/swagger-ui.html |
This URL will open the OpenAPI documentation in a web browser. The documentation provides an overview of the API operations and the input parameters.
Customizing the OpenAPI Documentation
springdoc provides several options for customizing the generated OpenAPI documentation. For example, we can customize the title and description of the documentation using the @OpenAPIDefinition annotation:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
@OpenAPIDefinition( info = @Info( title = "My API", description = "My awesome API", version = "1.0.0" ) ) @SpringBootApplication @EnableOpenApi public class MyApplication { public static void main(String[] args) { SpringApplication.run(MyApplication.class, args); } } |
In this example, we have added the @OpenAPIDefinition annotation to the main Spring Boot application class to provide a custom title, description, and version for the OpenAPI documentation.
We can also customize the appearance of the OpenAPI documentation by modifying the application.yml or application.properties file. For example, we can change the default theme by adding the following line to the application.yml file:
|
1 2 3 4 5 |
springdoc.swagger-ui.theme: dark |
This will change the theme of the OpenAPI documentation to a dark theme.
Conclusion
In this tutorial, we have learned how to generate OpenAPI v3 documentation for Spring microservices using springdoc. We have seen how to add the necessary dependencies, enable springdoc, and customize the generated documentation. By following these steps, you can easily generate documentation for your RESTful APIs and make it available to your users.
