{"id":13494772,"url":"https://github.com/springdoc/springdoc-openapi","last_synced_at":"2025-05-12T04:58:46.406Z","repository":{"id":37540883,"uuid":"196475719","full_name":"springdoc/springdoc-openapi","owner":"springdoc","description":"Library for OpenAPI 3 with spring-boot","archived":false,"fork":false,"pushed_at":"2025-05-04T21:09:02.000Z","size":10493,"stargazers_count":3432,"open_issues_count":13,"forks_count":526,"subscribers_count":44,"default_branch":"main","last_synced_at":"2025-05-11T14:51:27.370Z","etag":null,"topics":["java","json-format","kotlin","oauth2","openapi","openapi-spec","openapi-specification","openapi3","rest-api","spring","spring-boot","spring-data-rest","spring-hateoas","spring-security","spring-webflux","springdoc-openapi","swagger","swagger-documentation","swagger-ui","yaml-format"],"latest_commit_sha":null,"homepage":"https://springdoc.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/springdoc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.adoc","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"springdoc-openapi","github":"springdoc"}},"created_at":"2019-07-11T23:08:20.000Z","updated_at":"2025-05-09T20:58:58.000Z","dependencies_parsed_at":"2023-12-19T07:15:09.374Z","dependency_job_id":"1952ebc0-2c5c-462f-84c6-2d29875b40dd","html_url":"https://github.com/springdoc/springdoc-openapi","commit_stats":{"total_commits":2209,"total_committers":123,"mean_commits":"17.959349593495936","dds":0.669533725667723,"last_synced_commit":"01eba0d7d4bd30cbb6b0b20239997c65a481ad55"},"previous_names":[],"tags_count":200,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springdoc%2Fspringdoc-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springdoc%2Fspringdoc-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springdoc%2Fspringdoc-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springdoc%2Fspringdoc-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/springdoc","download_url":"https://codeload.github.com/springdoc/springdoc-openapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253585643,"owners_count":21931743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","json-format","kotlin","oauth2","openapi","openapi-spec","openapi-specification","openapi3","rest-api","spring","spring-boot","spring-data-rest","spring-hateoas","spring-security","spring-webflux","springdoc-openapi","swagger","swagger-documentation","swagger-ui","yaml-format"],"created_at":"2024-07-31T19:01:27.982Z","updated_at":"2025-05-12T04:58:46.358Z","avatar_url":"https://github.com/springdoc.png","language":"Java","readme":"![Octocat](https://springdoc.org/img/banner-logo.svg)\n[![Build Status](https://ci-cd.springdoc.org:8443/buildStatus/icon?job=springdoc-openapi-starter-IC)](https://ci-cd.springdoc.org:8443/view/springdoc-openapi/job/springdoc-openapi-starter-IC/)\n[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=springdoc_springdoc-openapi\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=springdoc_springdoc-openapi)\n[![Known Vulnerabilities](https://snyk.io/test/github/springdoc/springdoc-openapi.git/badge.svg)](https://snyk.io/test/github/springdoc/springdoc-openapi.git)\n[![Stack Exchange questions](https://img.shields.io/stackexchange/stackoverflow/t/springdoc)](https://stackoverflow.com/questions/tagged/springdoc?tab=Votes)\n\nIMPORTANT: ``springdoc-openapi v1.8.0`` is the latest Open Source release supporting Spring Boot 2.x and 1.x. \n\nAn extended support for [*springdoc-openapi v1*](https://springdoc.org/v1) \nproject is now available for organizations that need support beyond 2023. \n\nFor more details, feel free to reach out: [sales@springdoc.org](mailto:sales@springdoc.org)\n\n``springdoc-openapi`` is on [Open Collective](https://opencollective.com/springdoc). If you ❤️ this project consider becoming a [sponsor](https://github.com/sponsors/springdoc).\n\nThis project is sponsored by\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://opensource.mercedes-benz.com/\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://springdoc.org/img/mercedes-benz.png\" height=\"10%\" width=\"10%\" /\u003e\n\u003c/a\u003e\n\u0026nbsp;\u0026nbsp;\n\n\u003ca href=\"https://www.dm-jobs.com/dmTECH/?locale=de_DE\u0026wt_mc=.display.github.sponsoring.logo\" target=\"_blank\"\u003e\n     \u003cimg src=\"https://springdoc.org/img/dmTECH_Logo.jpg\" height=\"10%\" width=\"10%\" /\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://www.contrastsecurity.com/\" target=\"_blank\"\u003e\n   \u003cimg src=\"https://springdoc.org/img/contrastsecurity.svg\" height=\"10%\" width=\"30%\" /\u003e\n\u003c/a\u003e\n\n \u003ca href=\"https://www.lvm.de/\" target=\"_blank\"\u003e\n   \u003cimg src=\"https://springdoc.org/img/LVM_Versicherung_2010_logo.svg.png\" height=\"10%\" width=\"25%\" /\u003e\n  \u003c/a\u003e\n \u003ca href=\"https://gdnext.com/\" target=\"_blank\"\u003e\n   \u003cimg src=\"https://springdoc.org/img/gdnext.png\" height=\"10%\" width=\"10%\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# Table of Contents\n\n- [Full documentation](#full-documentation)\n- [**Introduction**](#introduction)\n- [**Getting Started**](#getting-started)\n    - [Library for springdoc-openapi integration with spring-boot and swagger-ui](#library-for-springdoc-openapi-integration-with-spring-boot-and-swagger-ui)\n    - [Spring-boot with OpenAPI Demo applications.](#spring-boot-with-openapi-demo-applications)\n        - [Source Code for Demo Applications.](#source-code-for-demo-applications)\n        - [Demo Spring Boot 2 Web MVC with OpenAPI 3.](#demo-spring-boot-2-web-mvc-with-openapi-3)\n        - [Demo Spring Boot 2 WebFlux with OpenAPI 3.](#demo-spring-boot-2-webflux-with-openapi-3)\n        - [Demo Spring Boot 2 WebFlux with Functional endpoints OpenAPI 3.](#demo-spring-boot-2-webflux-with-functional-endpoints-openapi-3)\n        - [Demo Spring Boot 2 and Spring Hateoas with OpenAPI 3.](#demo-spring-boot-2-and-spring-hateoas-with-openapi-3)\n    - [Integration of the library in a Spring Boot 3.x project without the swagger-ui:](#integration-of-the-library-in-a-spring-boot-3x-project-without-the-swagger-ui)\n    - [Error Handling for REST using @ControllerAdvice](#error-handling-for-rest-using-controlleradvice)\n    - [Adding API Information and Security documentation](#adding-api-information-and-security-documentation)\n    - [spring-webflux support with Annotated Controllers](#spring-webflux-support-with-annotated-controllers)\n- [Acknowledgements](#acknowledgements)\n    - [Contributors](#contributors)\n    - [Additional Support](#additional-support)\n\n# [Full documentation](https://springdoc.org/)\n\n# **Introduction**\n\nThe springdoc-openapi Java library helps automating the generation of API documentation\nusing Spring Boot projects.\nspringdoc-openapi works by examining an application at runtime to infer API semantics\nbased on Spring configurations, class structure and various annotations.\n\nThe library automatically generates documentation in JSON/YAML and HTML formatted pages.\nThe generated documentation can be complemented using `swagger-api` annotations.\n\nThis library supports:\n\n* OpenAPI 3\n* Spring-boot v3 (Java 17 \u0026 Jakarta EE 9)\n* JSR-303, specifically for @NotNull, @Min, @Max, and @Size.\n* Swagger-ui\n* OAuth 2\n* GraalVM native images\n\nThe following video introduces the Library:\n\n* [https://youtu.be/utRxyPfFlDw](https://youtu.be/utRxyPfFlDw)\n\nFor *spring-boot v3* support, make sure you use [springdoc-openapi v2](https://springdoc.org/)\n\nThis is a community-based project, not maintained by the Spring Framework Contributors (Pivotal)\n\n# **Getting Started**\n\n## Library for springdoc-openapi integration with spring-boot and swagger-ui\n\n* Automatically deploys swagger-ui to a Spring Boot 3.x application\n* Documentation will be available in HTML format, using the\n  official [swagger-ui jars](https://github.com/swagger-api/swagger-ui.git).\n* The Swagger UI page should then be available at http://server:\n  port/context-path/swagger-ui.html and the OpenAPI description will be available at the\n  following url for json format: http://server:port/context-path/v3/api-docs\n    * `server`: The server name or IP\n    * `port`: The server port\n    * `context-path`: The context path of the application\n* Documentation can be available in yaml format as well, on the following path:\n  `/v3/api-docs.yaml`\n* Add the `springdoc-openapi-ui` library to the list of your project dependencies (No\n  additional configuration is needed):\n\nMaven\n```xml\n   \u003cdependency\u003e\n      \u003cgroupId\u003eorg.springdoc\u003c/groupId\u003e\n      \u003cartifactId\u003espringdoc-openapi-starter-webmvc-ui\u003c/artifactId\u003e\n      \u003cversion\u003elast-release-version\u003c/version\u003e\n   \u003c/dependency\u003e\n```\n\nGradle\n```groovy\nimplementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:latest'\n```\n\n* This step is optional: For custom path of the swagger documentation in HTML format, add\n  a custom springdoc property, in your spring-boot configuration file:\n\n```properties\n# swagger-ui custom path\nspringdoc.swagger-ui.path=/swagger-ui.html\n```\n\n## Spring-boot with OpenAPI Demo applications.\n\n### [Source Code for Demo Applications](https://github.com/springdoc/springdoc-openapi-demos/tree/master).\n\n## [Demo Spring Boot 3 Web MVC with OpenAPI 3](https://demos.springdoc.org/demo-spring-boot-3-webmvc).\n\n## [Demo Spring Boot 3 WebFlux with OpenAPI 3](https://demos.springdoc.org/demo-spring-boot-3-webflux/swagger-ui.html).\n\n## [Demo Spring Boot 3 WebFlux with Functional endpoints OpenAPI 3](https://demos.springdoc.org/demo-spring-boot-3-webflux-functional/swagger-ui.html).\n\n## [Demo Spring Boot 3 and Spring Cloud Function Web MVC](https://demos.springdoc.org/spring-cloud-function-webmvc).\n\n## [Demo Spring Boot 3 and Spring Cloud Function WebFlux](http://158.101.191.70:8085/swagger-ui.html).\n\n## [Demo Spring Boot 3 and Spring Cloud Gateway](https://demos.springdoc.org/demo-microservices/swagger-ui.html).\n\n![Branching](https://springdoc.org/img/pets.png)\n\n## Integration of the library in a Spring Boot 3.x project without the swagger-ui:\n\n* Documentation will be available at the following url for json format: http://server:\n  port/context-path/v3/api-docs\n    * `server`: The server name or IP\n    * `port`: The server port\n    * `context-path`: The context path of the application\n* Documentation will be available in yaml format as well, on the following\n  path : `/v3/api-docs.yaml`\n* Add the library to the list of your project dependencies. (No additional configuration\n  is needed)\n\nMaven\n```xml\n   \u003cdependency\u003e\n      \u003cgroupId\u003eorg.springdoc\u003c/groupId\u003e\n      \u003cartifactId\u003espringdoc-openapi-starter-webmvc-api\u003c/artifactId\u003e\n      \u003cversion\u003elast-release-version\u003c/version\u003e\n   \u003c/dependency\u003e\n```\n\nGradle\n```groovy\nimplementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:latest'\n```\n\n* This step is optional: For custom path of the OpenAPI documentation in Json format, add\n  a custom springdoc property, in your spring-boot configuration file:\n\n```properties\n# /api-docs endpoint custom path\nspringdoc.api-docs.path=/api-docs\n```\n\n* This step is optional: If you want to disable `springdoc-openapi` endpoints, add a\n  custom springdoc property, in your `spring-boot` configuration file:\n\n```properties\n# disable api-docs\nspringdoc.api-docs.enabled=false\n```\n\n## Error Handling for REST using @ControllerAdvice\n\nTo generate documentation automatically, make sure all the methods declare the HTTP Code\nresponses using the annotation: @ResponseStatus.\n\n## Adding API Information and Security documentation\n\nThe library uses spring-boot application auto-configured packages to scan for the\nfollowing annotations in spring beans: OpenAPIDefinition and Info.\nThese annotations declare, API Information: Title, version, licence, security, servers,\ntags, security and externalDocs.\nFor better performance of documentation generation, declare `@OpenAPIDefinition`\nand `@SecurityScheme` annotations within a Spring managed bean.\n\n## spring-webflux support with Annotated Controllers\n\n* Documentation can be available in yaml format as well, on the following path :\n  /v3/api-docs.yaml\n* Add the library to the list of your project dependencies (No additional configuration\n  is needed)\n\nMaven\n```xml\n   \u003cdependency\u003e\n      \u003cgroupId\u003eorg.springdoc\u003c/groupId\u003e\n      \u003cartifactId\u003espringdoc-openapi-starter-webflux-ui\u003c/artifactId\u003e\n      \u003cversion\u003elast-release-version\u003c/version\u003e\n   \u003c/dependency\u003e\n```\n\nGradle\n```groovy\nimplementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:latest'\n```\n\n* This step is optional: For custom path of the swagger documentation in HTML format, add\n  a custom springdoc property, in your spring-boot configuration file:\n\n```properties\n# swagger-ui custom path\nspringdoc.swagger-ui.path=/swagger-ui.html\n```\n\nThe `springdoc-openapi` libraries are hosted on maven central repository.\nThe artifacts can be viewed accessed at the following locations:\n\nReleases:\n\n* [https://central.sonatype.com/search?q=g:org.springdoc)](https://central.sonatype.com/search?q=g:org.springdoc)\n  .\n\nSnapshots:\n\n* [https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/org/springdoc/](https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/org/springdoc/)\n  .\n\n# Acknowledgements\n\n## Contributors\n\nspringdoc-openapi is relevant and updated regularly due to the valuable contributions from\nits [contributors](https://github.com/springdoc/springdoc-openapi/graphs/contributors).\n\n\u003ca href=\"https://github.com/springdoc/springdoc-openapi/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=springdoc/springdoc-openapi\" width=\"50%\"/\u003e\n\u003c/a\u003e\n\nThanks you all for your support!\n\n## Additional Support\n\n* [Spring Team](https://spring.io/team) - Thanks for their support by sharing all relevant\n  resources around Spring projects.\n* [JetBrains](https://www.jetbrains.com/?from=springdoc-openapi) - Thanks a lot for\n  supporting springdoc-openapi project.\n\n![JenBrains logo](https://springdoc.org/img/jetbrains.svg)\n","funding_links":["https://opencollective.com/springdoc-openapi","https://github.com/sponsors/springdoc","https://opencollective.com/springdoc"],"categories":["Java","Projects","项目","Uncategorized"],"sub_categories":["REST Frameworks","REST框架","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspringdoc%2Fspringdoc-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspringdoc%2Fspringdoc-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspringdoc%2Fspringdoc-openapi/lists"}