OpenAPI | Creating an API description of your project using SpringDoc implementation
The main article that bundles all together and redirects to different features that you can implement in swagger UI is present here: https://medium.com/@stefan.paladuta17/spring-boot-using-springdoc-at-maximum-37a58c63fc19
In this article I am going to present what the implementation of spring-doc (that is complaint with OpenAPI specifications) brings to the table.
The article will be divided in the following chapters:
- Chapter 1 Implementing springdoc first steps
- Chapter 2 Properties we can change
- Chapter 3 Using springdoc-openapi Maven Plugin to generate yaml or json file that can be imported in Postman, Insomnia or other similar tools
- Chapter 4 Annotations that you should know
- Chapter 5 Configuration of the openAPI definition via annotation
Chapter 1 Implementing spring-doc first steps
Step 1 Add the dependency into your spring boot project
Once we add the dependency everything will be generated to the OpenAPI specifications:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId
<version>1.6.4</version>
</dependency>NOTE: This version 1.6.4 is what I choose in present (03/07/2022) but don’t forget you can always check the version in the maven repository: https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui
Step 2 Create your first Controller
and now if you start your project, going to: http://localhost<yourPort>/swagger-ui/index.html you can see:
Chapter 2 Properties we can change
Springdoc-openapi also supports swagger-ui properties. These can be used as Spring Boot properties, with the prefix springdoc.swagger-ui.
Example 1: springdoc.swagger-ui.path=/swagger-ui-custom.html
will change the UI page location url from http://localhost<yourPort>/swagger-ui/index.html to http://localhost<yourPort>/swagger-ui-custom.html if you want to go more fancy.
Example 2: springdoc.swagger-ui.operationsSorter=method
sorting the API paths in order of their HTTP methods.
more can be found here: https://springdoc.org/#properties
Chapter 3 Using springdoc-openapi Maven Plugin to generate yaml or json file that can be imported in Postman, Insomnia or other similar tools
Origin: https://github.com/springdoc/springdoc-openapi-maven-plugin
So, we have a maven plugin that we can use to generate the openapi.json, maybe you are asking why is this cool ? Well for multiple reasons but first allow me to show the steps to add this plugin
Step 1 — Putting the dependency:
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>2.3.4.RELEASE</version>
<configuration>
<jvmArguments>-Dspring.application.admin.enabled=true</jvmArguments>
</configuration>
<executions>
<execution>
<id>pre-integration-test</id>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>post-integration-test</id>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-maven-plugin</artifactId>
<version>1.1</version>
<executions>
<execution>
<id>integration-test</id>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>the complete pom.xml looks like this:
and now we call it in a terminal: mvn verify
and now after the generated openapi.json I’m using Postman to integrate it:
Chapter 4 Annotations that you should know
Remove springfox and swagger 2 dependencies. Add springdoc-openapi-ui dependency instead. Replace swagger 2 annotations with swagger 3 annotations (it is already included with springdoc-openapi-ui dependency). Package for swagger 3 annotations is io.swagger.v3.oas.annotations.
Annotation @Tag
NOTE: In springfox implementation this tag represents the equivalent of the tag @Api you can read about it here: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-all-annotations-that-we-should-know-about-in-springfox-e419e575b078 (Chapter: @Api annotation)
Example of usage:
@Tag(description = "Book Store details that will appear in the UI", name = "Books store")
public class BookController {
...
}Annotation @Parameter
Example of usage:
...
@GetMapping("/bookshop")
@Operation(summary = "Get book store name")
public String getBookShopName(@Parameter(in = ParameterIn.COOKIE) String cookie) {
return "Stefan's books shop name";
}
...Parameter annotation can accept one of the following types:
⚙️ ParameterIn.COOKIE
@GetMapping("/bookshop1")
@Operation(summary = "Get book store name | Cookie Example")
public String getBookShopNameWithCookieExample1(@Parameter(in = ParameterIn.COOKIE) String cookie) {
return "Stefan's books shop name";
}
⚙️ParameterIn.QUERY
@GetMapping("/bookshop3")
@Operation(summary = "Get book store name | QUERY Example")
public String getBookShopNameWithCookieExample3(@Parameter(in = ParameterIn.QUERY) String yearOfPublication) {
return "Stefan's books shop name";
}
⚙️ParameterIn.HEADER
@GetMapping("/bookshop2")
@Operation(summary = "Get book store name | Header Example")
public String getBookShopNameWithCookieExample2(@Parameter(in = ParameterIn.HEADER) String token) {
return "Stefan's books shop name";
}
⚙️ParameterIn.PATH
@GetMapping("/bookshop4/{id}")
@Operation(summary = "Get book store name | PATH Example")
public String getBookShopNameWithCookieExample4(@Parameter(in = ParameterIn.PATH) String id) {
return "Stefan's books shop name";
}
Annotation @Hidden
NOTE: In springfox implementation this tag represents the equivalent of the tag @ApiIgnore you can read about it here: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-all-annotations-that-we-should-know-about-in-springfox-e419e575b078 (Chapter: @ApiIgnore annotation)
As the name states it’s used to not render an operation or parameter actually here you have 3 options to hide something:
- Option 1 — Use
@Hiddenfor parameters or/and operations/endpoints. - Option 2 — Use
@Parameter(hidden = true)just for parameters. - Option 3 — Use
@Operation(hidden = true)just for operations / endpoints.
Annotation @Schema
The @Schema annotation is used to customize the name of the schema also properties can be customized too and not only with boring text but also with emojis 😋, example:
- Introducing into the project a DTO and a new endpoint that recovers a collection of instances of that DTO:
import lombok.Data;@Data
public class Book {
private String title;
private String[] authors;
}
and the result is:
ok fine, we see the resource called Book, but it’s a bit boring. How can we spice it up ? well… with the @Schema annotation:
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;@Data
@Schema(name="Book 📚", description="Book characteristic")
public class Book {
@Schema(description="Book Tittle", maxLength=50)
private String title;
private String[] authors;
}
and now:
well that’s a resource if I may say 😋
Annotation @Operation
NOTE: In springfox implementation this tag represents the equivalent of the tag @ApiOperation you can read about it here: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-all-annotations-that-we-should-know-about-in-springfox-e419e575b078 (Chapter: @ApiOperation annotation)
Example of usage:
[...]
@GetMapping("/bookshop/books")
@Operation(summary = "Get books", description = "A good description applied to a wonderful endpoint :)")
public List<Book> getBooks() {
return new ArrayList<Book>();
}
[...]
Chapter 5 Configuration of the openAPI definition via annotation
So, except the style of creating a java class “OpenAPI” we have the posibility also to do the same thing via annotation.
Using the OpenAPI object:
Using annotation:
Without annotation and also without OpenAPI bean object:
If you liked the article please take a minute to offer me a clap 👏 or even buy me a coffee https://www.buymeacoffee.com/stefansplace (;
If you want my code you can find it here: https://github.com/Kanames/SpringBoot-OpenApiExamples
References:
