[IntelliJ IDEA] springdoc-openapi automatically generates OpenAPI (Swagger) documentation in JSON/YAML and HTML format APIs in Spring Boot

Posted on Edited on In , , , , Views: Word count in article: 4.5k Reading time ≈ 4 mins.

springdoc-openapi

springdoc-openapi java library helps automating the generation of API documentation using spring boot projects. springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations.

Swagger is a simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale API Documentation & Design Tools for Teams | Swagger - https://swagger.io/tools/.

Features

springdoc-openapi automatically generates documentation in JSON/YAML and HTML format APIs. This documentation can be completed by comments using swagger-api annotations.

This library supports:

  • OpenAPI 3

  • Spring-boot (v1 and v2)

  • JSR-303, specifically for @NotNull, @Min, @Max, and @Size.

  • Swagger-ui

  • OAuth 2

  • GraalVM native images

Gradle

Create or update gradle.files/springdoc-openapi-ui.gradle file.

1
2
3
4
5
6
// gradle.files/springdoc-openapi-ui.gradle

dependencies {
    // https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui
    implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.5.10'
}

Apply gradle.files/springdoc-openapi-ui.gradle file in bundle.gradle file.

1
2
3
// bundle.gradle

apply from: 'gradle.files/springdoc-openapi-ui.gradle'

Maven

1
2
3
4
5
6
<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.10</version>
</dependency>

Getting Started

This will automatically deploy swagger-ui to a spring-boot application:

  • Documentation will be available in HTML format, using the official swagger-ui jars - https://github.com/swagger-api/swagger-ui.

  • The Swagger UI page will then be available at http://server:port/context-path/swagger-ui.html and the OpenAPI description will be available at the following url for json format: http://server:port/context-path/v3/api-docs

For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file: .

1
2
3
4
# src/main/resources/application.properties

# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

For custom path of the OpenAPI documentation in Json format, add a custom springdoc property, in your spring-boot configuration file:

1
2
3
4
# src/main/resources/application.properties

# /api-docs endpoint custom path
springdoc.api-docs.path=/api-docs

  • server: The server name or IP

  • port: The server port

  • context-path: The context path of the application

Documentation can be available in yaml format as well, on the following path : /v3/api-docs.yaml

Advance

Spring security support

For a project that uses spring-security, you should add the following dependency, together with the springdoc-openapi-ui dependency: This dependency helps ignoring @AuthenticationPrincipal in case its used on REST Controllers.

Gradle

1
2
3
4
dependencies {
    // https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-security
    implementation group: 'org.springdoc', name: 'springdoc-openapi-security', version: '1.5.10'
}

Maven

1
2
3
4
5
6
<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-security -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-security</artifactId>
    <version>1.5.10</version>
</dependency>

Disabling the springdoc-openapi endpoints

In order to disable the springdoc-openapi endpoint (/v3/api-docs by default) use the following property:

1
2
3
4
# src/main/resources/application.properties

# Disabling the /v3/api-docs enpoint
springdoc.api-docs.enabled=false

Disabling the swagger-ui

In order to disable the swagger-ui, use the following property:

1
2
3
4
# src/main/resources/application.properties

# Disabling the swagger-ui
springdoc.swagger-ui.enabled=false

References

[1] springdoc/springdoc-openapi: Library for OpenAPI 3 with spring-boot - https://github.com/springdoc/springdoc-openapi

[2] OpenAPI 3 Library for spring-boot - https://springdoc.org/

[3] Maven Repository: org.springdoc » springdoc-openapi-ui - https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui

[4] Maven Repository: org.springdoc » springdoc-openapi-security - https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-security

[5] Springdoc-openapi Properties - https://springdoc.org/#properties

[6] swagger-api/swagger-ui: Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API. - https://github.com/swagger-api/swagger-ui

[7] API Documentation & Design Tools for Teams | Swagger - https://swagger.io/

[8] Spring Boot - https://spring.io/projects/spring-boot