Skip to the content.

Octocat

Introduction

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.

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

This library supports:

This is a community-based project, not maintained by the Spring Framework Contributors (Pivotal)

Getting Started

Library for springdoc-openapi integration with spring-boot and swagger-ui

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.3.0</version>
   </dependency>
# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

Integration of the libray in a spring-boot project without the swagger-ui:

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-webmvc-core</artifactId>
      <version>1.3.0</version>
   </dependency>
# /api-docs endpoint custom path
springdoc.api-docs.path=/api-docs
   <dependency>
	  <groupId>org.webjars</groupId>
	  <artifactId>webjars-locator-jboss-vfs</artifactId>
	  <version>0.1.0</version>
   </dependency>

Additonnal settings

Adding API Information and Security documentation

The library uses spring-boot application auto-configured packages to scan for the following annotations in spring beans: OpenAPIDefinition and Info. These annotations declare, API Information: Title, version, licence, security, servers, tags, security and externalDocs. For better performance of documentation generation, declare @OpenAPIDefinition and @SecurityScheme annotations within a spring managed bean.

Error Handling for REST using @ControllerAdvice

To generate documentation automatically, make sure all the methods declare the HTTP Code responses using the annotation: @ResponseStatus

Disabling the springdoc-openapi endpoints

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

# 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:

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

Swagger-ui configuration

The library supports the swagger-ui official properties:

You need to declare swagger-ui properties as spring-boot properties. All these properties should be declared with the following prefix: springdoc.swagger-ui

Selecting the Rest Controllers to include in the documentation

Additionally to @Hidden annotation from swagger-annotations, its possible to restrict the generated OpenAPI description using package or path configuration.

For the list of packages to include, use the following property:

# Packages to include
springdoc.packagesToScan=com.package1, com.package2

For the list of paths to include, use the following property:

# Paths to include
springdoc.pathsToMatch=/v1, /api/balance/**

Spring-weblfux support with Annotated Controllers

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-webflux-ui</artifactId>
      <version>1.3.0</version>
   </dependency>
# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

Spring Pageable support

The support for Pageable of spring-data-commons is available. The projects that use Pageable type should add this dependency together with the springdoc-openapi-ui dependency.

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-data-rest</artifactId>
      <version>1.3.0</version>
   </dependency>

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.

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-security</artifactId>
      <version>1.3.0</version>
   </dependency>

Kotlin support

For a project that uses kotlin, you should add the following dependency, together with the springdoc-openapi-ui dependency: This dependency improves the support of kotlin types:

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-kotlin</artifactId>
      <version>1.3.0</version>
   </dependency>

Introduction to springdoc-openapi-maven-plugin

The aim of springdoc-openapi-maven-plugin is to generate json and yaml OpenAPI description during build time. The plugin works during integration-tests phase, and generate the OpenAPI description. The plugin works in conjunction with spring-boot-maven plugin.

You can test it during the integration tests phase using the maven command:

mvn verify -Dspring.application.admin.enabled=true

In order to use this functionality, you need to add the plugin declaration on the plugins section of your pom.xml:

<plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 <version>2.1.8.RELEASE</version>
 <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>0.3</version>
 <executions>
  <execution>
   <id>integration-test</id>
   <goals>
    <goal>generate</goal>
   </goals>
  </execution>
 </executions>
<plugin>

For more custom settings of the springdoc-openapi-maven-plugin, you can consult the plugin documentation:

Introduction to springdoc-openapi-gradle-plugin

This plugin allows you to generate an OpenAPI 3 specification for a Spring Boot application from a Gradle build.

plugins {
      id("org.springframework.boot") version "2.2.4.RELEASE"
      id "com.github.johnrengelman.processes" version "0.5.0"
      id("org.springdoc.openapi-gradle-plugin") version "1.0.0"
}

When you add this plugin and its runtime dependency plugins to your build file, the plugin creates the following tasks:

gradle clean generateOpenApiDocs

For more custom configuration of springdoc-openapi-gradle-plugin ,you can consult the plugin documentation:

springdoc applications demos

Demo Spring Boot 2 webmvc with OpenAPI 3.

Demo Spring Boot 2 webflux with OpenAPI 3.

Demo Spring Boot 1 webmvc with OpenAPI 3.

Branching

Source code of the Demo Applications

Dependencies repository

The springdoc-openapi libraries are hosted on maven central repository. The artifacts can be viewed accessed at the following locations:

Releases:

Snapshots:

Spring Data REST support

There no automatic generation planned to spring-data-rest annotations. You need to use OAS3 annotations on your spring-data-rest parameters. You can also contribute to add the support for the different annotations (@RepositoryRestResource, @QueryDSL, …)

Spring-weblfux with Functional Endpoints, will be available in the future release