Springdoc Openapi

Library for OpenAPI 3 with spring-boot
Alternatives To Springdoc Openapi
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Springfox5,78913,0905833 months ago26July 14, 2020295apache-2.0Java
Automated JSON API documentation for API's built with Spring
Springdoc Openapi2,6235294 days ago139August 21, 20226apache-2.0Java
Library for OpenAPI 3 with spring-boot
Spring Restdocs1,1041214413 days ago21January 15, 202242apache-2.0Java
Test-driven documentation for RESTful services
Springdoc Openapi Demos400
3 days ago14May 06, 20203Java
Demo for OpenAPI 3 with spring-boot
Spring Petclinic Rest383
a month ago8apache-2.0Java
REST version of the Spring Petclinic sample application
Restdocs Api Spec299
22 days ago14May 02, 202235mitKotlin
Adds API specification support to Spring REST Docs
Curso Especialista Spring Rest264
14 days agoJava
Projeto do curso Especialista Spring REST da AlgaWorks
Hikaku179610 months ago15September 02, 202117apache-2.0Kotlin
A library that tests if the implementation of a REST-API meets its specification.
Springdoc Openapi Gradle Plugin106
4 days ago15apache-2.0Kotlin
Library for OpenAPI 3 with spring-boot
Springdoc Openapi Maven Plugin106
4 days ago7March 20, 20222apache-2.0Java
Library for OpenAPI 3 with spring-boot
Alternatives To Springdoc Openapi
Select To Compare


Alternative Project Comparisons
Readme

Octocat Build Status Quality Gate Known Vulnerabilities Stack Exchange questions

springdoc-openapi is on Open Collective.

If you ❤️ this project consider becoming a sponsor. If you already use the springdoc-openapi, please do not forget adding a github star to this repository.

This project is sponsored by

  

Table of Contents

Full documentation

Introduction

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

For spring-boot v3 support, make sure you use springdoc-openapi v2

The following video introduces the Library:

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

  • 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

Spring-boot with OpenAPI Demo applications.

Source Code for Demo Applications.

Demo Spring Boot 2 Web MVC with OpenAPI 3.

Demo Spring Boot 2 WebFlux with OpenAPI 3.

Demo Spring Boot 1 Web MVC with OpenAPI 3.

Demo Spring Boot 2 WebFlux with Functional endpoints OpenAPI 3.

Demo Spring Boot 2 and Spring Hateoas with OpenAPI 3.

Branching

Integration of the library in a Spring Boot 2.x.x project without the swagger-ui:

  • 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

Error Handling for REST using @ControllerAdvice

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

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.

spring-webflux support with Annotated Controllers

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

Snapshots:

Acknowledgements

Contributors

springdoc-openapi is relevant and updated regularly due to the valuable contributions from its contributors.

Thank you all for your support!

Additional Support

  • Spring Team - Thanks for their support by sharing all relevant resources around Spring projects.
  • JetBrains - Thanks a lot for supporting springdoc-openapi project.

JenBrains logo

Popular Openapi Projects
Popular Spring Projects
Popular Application Programming Interfaces Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Java
Kotlin
Spring
Rest Api
Spring Boot
Oauth2
Annotations
Swagger
Openapi
Openapi3
Spring Security
Swagger Ui
Openapi Specification