The 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.

The library automatically generates documentation in JSON/YAML and HTML formatted pages. The generated documentation can be complemented 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

The following video introduces the Library:

• https://youtu.be/utRxyPfFlDw

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

• Automatically deploys swagger-ui to a Spring Boot 2.x application
• Documentation will be available in HTML format, using the official swagger-ui jars.
• The Swagger UI page should 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
  • 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
• Add the springdoc-openapi-ui library to the list of your project dependencies (No additional configuration is needed):

 <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>last-release-version</version> </dependency>

• This step is optional: For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file:

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

• https://github.com/springdoc/springdoc-openapi-demos.git.

• Documentation will be available at the following url for json format: http://server:port/context-path/v3/api-docs
  • server: The server name or IP
  • port: The server port
  • context-path: The context path of the application
• Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml
• Add the library to the list of your project dependencies. (No additional configuration is needed)

 <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-webmvc-core</artifactId> <version>last-release-version</version> </dependency>

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

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

• This step is optional: If you want to disable springdoc-openapi endpoints, add a custom springdoc property, in your spring-boot configuration file:

# disable api-docs springdoc.api-docs.enabled=false

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

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.

• Documentation can be available in yaml format as well, on the following path : /v3/api-docs.yaml
• Add the library to the list of your project dependencies ( No additional configuration is needed)

 <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-webflux-ui</artifactId> <version>last-release-version</version> </dependency>

• This step is optional: For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file:

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

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

Releases:

• https://oss.sonatype.org/content/groups/public/org/springdoc/.

Snapshots:

• https://oss.sonatype.org/content/repositories/snapshots/org/springdoc/.

• Thanks a lot JetBrains for supporting springdoc-openapi project.