springdoc openapi

WICHTIG: springdoc-openapi v1.8.0 ist die neueste Open-Source-Version, die Spring Boot 2.x und 1.x unterstützt.

Für Organisationen, die über 2023 hinaus Unterstützung benötigen, ist jetzt eine erweiterte Unterstützung für das Projekt springdoc-openapi v1 verfügbar.

Für weitere Informationen wenden Sie sich bitte an: [email protected]

springdoc-openapi ist auf Open Collective. Wenn Sie dieses Projekt ❤️, denken Sie darüber nach, Sponsor zu werden.

Dieses Projekt wird gefördert von

Inhaltsverzeichnis

• Vollständige Dokumentation
• Einführung
• Erste Schritte
  • Bibliothek für die Springdoc-Openapi-Integration mit Spring-Boot und Swagger-UI
  • Spring-Boot mit OpenAPI-Demoanwendungen.
    • Quellcode für Demoanwendungen.
    • Demo von Spring Boot 2 Web MVC mit OpenAPI 3.
    • Demo von Spring Boot 2 WebFlux mit OpenAPI 3.
    • Demo von Spring Boot 2 WebFlux mit funktionalen Endpunkten OpenAPI 3.
    • Demo von Spring Boot 2 und Spring Hateoas mit OpenAPI 3.
  • Integration der Bibliothek in ein Spring Boot 3.x-Projekt ohne swagger-ui:
  • Fehlerbehandlung für REST mit @ControllerAdvice
  • Hinzufügen von API-Informationen und Sicherheitsdokumentation
  • Spring-Webflux-Unterstützung mit annotierten Controllern
• Danksagungen
  • Mitwirkende
  • Zusätzliche Unterstützung

Vollständige Dokumentation

Einführung

Die Java-Bibliothek springdoc-openapi hilft bei der Automatisierung der Generierung der API-Dokumentation mithilfe von Spring Boot-Projekten. springdoc-openapi untersucht eine Anwendung zur Laufzeit, um API-Semantik basierend auf Spring-Konfigurationen, Klassenstruktur und verschiedenen Anmerkungen abzuleiten.

Die Bibliothek generiert automatisch Dokumentation in JSON/YAML- und HTML-formatierten Seiten. Die generierte Dokumentation kann durch swagger-api -Annotationen ergänzt werden.

Diese Bibliothek unterstützt:

• OpenAPI 3
• Spring-Boot v3 (Java 17 & Jakarta EE 9)
• JSR-303, speziell für @NotNull, @Min, @Max und @Size.
• Swagger-ui
• OAuth 2
• Native GraalVM-Bilder

Das folgende Video stellt die Bibliothek vor:

• https://youtu.be/utRxyPfFlDw

Stellen Sie für die Unterstützung von Spring-Boot v3 sicher, dass Sie springdoc-openapi v2 verwenden

Dies ist ein Community-basiertes Projekt, das nicht von den Spring Framework Contributors (Pivotal) verwaltet wird.

Erste Schritte

Bibliothek für die Springdoc-Openapi-Integration mit Spring-Boot und Swagger-UI

• Stellt swagger-ui automatisch für eine Spring Boot 3.x-Anwendung bereit
• Die Dokumentation wird im HTML-Format unter Verwendung der offiziellen Swagger-UI-JARs verfügbar sein.
• Die Swagger-UI-Seite sollte dann unter http://server:port/context-path/swagger-ui.html verfügbar sein und die OpenAPI-Beschreibung ist unter der folgenden URL für das JSON-Format verfügbar: http://server:port/context -path/v3/api-docs
  • server : Der Servername oder die IP
  • port : Der Server-Port
  • context-path : Der Kontextpfad der Anwendung
• Die Dokumentation kann auch im Yaml-Format unter folgendem Pfad verfügbar sein: /v3/api-docs.yaml
• Fügen Sie die springdoc-openapi-ui Bibliothek zur Liste Ihrer Projektabhängigkeiten hinzu (keine zusätzliche Konfiguration erforderlich):

Maven

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

Gradle

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Dieser Schritt ist optional: Für einen benutzerdefinierten Pfad der Swagger-Dokumentation im HTML-Format fügen Sie eine benutzerdefinierte Springdoc-Eigenschaft in Ihrer Spring-Boot-Konfigurationsdatei hinzu:

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

Spring-Boot mit OpenAPI-Demoanwendungen.

Quellcode für Demoanwendungen.

Demo von Spring Boot 3 Web MVC mit OpenAPI 3.

Demo von Spring Boot 3 WebFlux mit OpenAPI 3.

Demo von Spring Boot 3 WebFlux mit funktionalen Endpunkten OpenAPI 3.

Demo von Spring Boot 3 und Spring Cloud Function Web MVC.

Demo von Spring Boot 3 und Spring Cloud Function WebFlux.

Demo von Spring Boot 3 und Spring Cloud Gateway.

Integration der Bibliothek in ein Spring Boot 3.x-Projekt ohne swagger-ui:

• Die Dokumentation ist unter der folgenden URL für das JSON-Format verfügbar: http://server: port/context-path/v3/api-docs
  • server : Der Servername oder die IP
  • port : Der Server-Port
  • context-path : Der Kontextpfad der Anwendung
• Die Dokumentation wird auch im Yaml-Format unter folgendem Pfad verfügbar sein: /v3/api-docs.yaml
• Fügen Sie die Bibliothek zur Liste Ihrer Projektabhängigkeiten hinzu. (Es ist keine zusätzliche Konfiguration erforderlich)

Maven

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

Gradle

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Dieser Schritt ist optional: Für einen benutzerdefinierten Pfad der OpenAPI-Dokumentation im Json-Format fügen Sie eine benutzerdefinierte Springdoc-Eigenschaft in Ihrer Spring-Boot-Konfigurationsdatei hinzu:

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

• Dieser Schritt ist optional: Wenn Sie springdoc-openapi -Endpunkte deaktivieren möchten, fügen Sie eine benutzerdefinierte springdoc-Eigenschaft in Ihrer spring-boot -Konfigurationsdatei hinzu:

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

Fehlerbehandlung für REST mit @ControllerAdvice

Um die Dokumentation automatisch zu generieren, stellen Sie sicher, dass alle Methoden die HTTP-Code-Antworten mit der Annotation @ResponseStatus deklarieren.

Hinzufügen von API-Informationen und Sicherheitsdokumentation

Die Bibliothek verwendet automatisch konfigurierte Pakete der Spring-Boot-Anwendung, um nach den folgenden Anmerkungen in Spring Beans zu suchen: OpenAPIDefinition und Info. Diese Anmerkungen deklarieren API-Informationen: Titel, Version, Lizenz, Sicherheit, Server, Tags, Sicherheit und externe Dokumente. Für eine bessere Leistung der Dokumentationsgenerierung deklarieren Sie die Annotationen @OpenAPIDefinition und @SecurityScheme in einer von Spring verwalteten Bean.

Spring-Webflux-Unterstützung mit annotierten Controllern

• Die Dokumentation kann auch im Yaml-Format unter folgendem Pfad verfügbar sein: /v3/api-docs.yaml
• Fügen Sie die Bibliothek zur Liste Ihrer Projektabhängigkeiten hinzu (keine zusätzliche Konfiguration erforderlich)

Maven

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

Gradle

implementation ' org.springdoc:springdoc-openapi-starter-webmvc-ui:latest '

• Dieser Schritt ist optional: Für einen benutzerdefinierten Pfad der Swagger-Dokumentation im HTML-Format fügen Sie eine benutzerdefinierte Springdoc-Eigenschaft in Ihrer Spring-Boot-Konfigurationsdatei hinzu:

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

Die springdoc-openapi -Bibliotheken werden im zentralen Maven-Repository gehostet. Die Artefakte können an folgenden Orten besichtigt werden:

Veröffentlichungen:

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

Schnappschüsse:

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

Danksagungen

Mitwirkende

springdoc-openapi ist aufgrund der wertvollen Beiträge seiner Mitwirkenden relevant und wird regelmäßig aktualisiert.

Vielen Dank an alle für eure Unterstützung!

Zusätzliche Unterstützung

• Spring-Team – Vielen Dank für ihre Unterstützung durch die Weitergabe aller relevanten Ressourcen rund um Spring-Projekte.
• JetBrains – Vielen Dank für die Unterstützung des Springdoc-Openapi-Projekts.