springdoc openapi

PENTING: springdoc-openapi v1.8.0 adalah rilis Open Source terbaru yang mendukung Spring Boot 2.x dan 1.x.

Dukungan tambahan untuk proyek springdoc-openapi v1 kini tersedia untuk organisasi yang membutuhkan dukungan setelah tahun 2023.

Untuk detail lebih lanjut, silakan menghubungi: [email protected]

springdoc-openapi ada di Open Collective. Jika Anda ❤️ proyek ini pertimbangkan untuk menjadi sponsor.

Proyek ini disponsori oleh

Daftar isi

• Dokumentasi lengkap
• Perkenalan
• Memulai
  • Perpustakaan untuk integrasi springdoc-openapi dengan spring-boot dan swagger-ui
  • Spring-boot dengan aplikasi Demo OpenAPI.
    • Kode Sumber untuk Aplikasi Demo.
    • Demo Spring Boot 2 Web MVC dengan OpenAPI 3.
    • Demo Spring Boot 2 WebFlux dengan OpenAPI 3.
    • Demo Spring Boot 2 WebFlux dengan titik akhir fungsional OpenAPI 3.
    • Demo Spring Boot 2 dan Spring Hateoas dengan OpenAPI 3.
  • Integrasi perpustakaan dalam proyek Spring Boot 3.x tanpa swagger-ui:
  • Penanganan Kesalahan untuk REST menggunakan @ControllerAdvice
  • Menambahkan dokumentasi Informasi dan Keamanan API
  • dukungan spring-webflux dengan Pengontrol Beranotasi
• Ucapan Terima Kasih
  • Kontributor
  • Dukungan Tambahan

Dokumentasi lengkap

Perkenalan

Pustaka Java springdoc-openapi membantu mengotomatiskan pembuatan dokumentasi API menggunakan proyek Spring Boot. springdoc-openapi bekerja dengan memeriksa aplikasi saat runtime untuk menyimpulkan semantik API berdasarkan konfigurasi Spring, struktur kelas, dan berbagai anotasi.

Pustaka secara otomatis menghasilkan dokumentasi dalam halaman berformat JSON/YAML dan HTML. Dokumentasi yang dihasilkan dapat dilengkapi dengan anotasi swagger-api .

Perpustakaan ini mendukung:

• Buka API 3
• Spring-boot v3 (Jawa 17 & Jakarta EE 9)
• JSR-303, khusus untuk @NotNull, @Min, @Max, dan @Size.
• Kesombongan-ui
• OAuth 2
• Gambar asli GraalVM

Video berikut memperkenalkan Perpustakaan:

• https://youtu.be/utRxyPfFlDw

Untuk dukungan spring-boot v3 , pastikan Anda menggunakan springdoc-openapi v2

Ini adalah proyek berbasis komunitas, tidak dikelola oleh Kontributor Spring Framework (Pivotal)

Memulai

Perpustakaan untuk integrasi springdoc-openapi dengan spring-boot dan swagger-ui

• Secara otomatis menyebarkan swagger-ui ke aplikasi Spring Boot 3.x
• Dokumentasi akan tersedia dalam format HTML, menggunakan toples resmi swagger-ui.
• Halaman Swagger UI kemudian akan tersedia di http://server: port/context-path/swagger-ui.html dan deskripsi OpenAPI akan tersedia di url berikut untuk format json: http://server:port/context -path/v3/api-docs
  • server : Nama server atau IP
  • port : Pelabuhan server
  • context-path : Jalur konteks aplikasi
• Dokumentasi juga dapat tersedia dalam format yaml, di jalur berikut: /v3/api-docs.yaml
• Tambahkan pustaka springdoc-openapi-ui ke daftar dependensi proyek Anda (Tidak diperlukan konfigurasi tambahan):

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 '

• Langkah ini opsional: Untuk jalur khusus dokumentasi angkuh dalam format HTML, tambahkan properti springdoc khusus, di file konfigurasi spring-boot Anda:

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

Spring-boot dengan aplikasi Demo OpenAPI.

Kode Sumber untuk Aplikasi Demo.

Demo Spring Boot 3 Web MVC dengan OpenAPI 3.

Demo Spring Boot 3 WebFlux dengan OpenAPI 3.

Demo Spring Boot 3 WebFlux dengan titik akhir fungsional OpenAPI 3.

Demo Spring Boot 3 dan Web MVC Fungsi Cloud Spring.

Demo Spring Boot 3 dan Spring Cloud Function WebFlux.

Demo Spring Boot 3 dan Spring Cloud Gateway.

Integrasi perpustakaan dalam proyek Spring Boot 3.x tanpa swagger-ui:

• Dokumentasi akan tersedia di url berikut untuk format json: http://server: port/context-path/v3/api-docs
  • server : Nama server atau IP
  • port : Pelabuhan server
  • context-path : Jalur konteks aplikasi
• Dokumentasi juga akan tersedia dalam format yaml, di jalur berikut: /v3/api-docs.yaml
• Tambahkan perpustakaan ke daftar dependensi proyek Anda. (Tidak diperlukan konfigurasi tambahan)

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 '

• Langkah ini opsional: Untuk jalur khusus dokumentasi OpenAPI dalam format Json, tambahkan properti springdoc khusus, di file konfigurasi spring-boot Anda:

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

• Langkah ini opsional: Jika Anda ingin menonaktifkan titik akhir springdoc-openapi , tambahkan properti springdoc khusus, di file konfigurasi spring-boot Anda:

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

Penanganan Kesalahan untuk REST menggunakan @ControllerAdvice

Untuk menghasilkan dokumentasi secara otomatis, pastikan semua metode mendeklarasikan respons Kode HTTP menggunakan anotasi: @ResponseStatus.

Menambahkan dokumentasi Informasi dan Keamanan API

Pustaka menggunakan paket konfigurasi otomatis aplikasi spring-boot untuk memindai anotasi berikut di spring beans: OpenAPIDefinition dan Info. Anotasi ini menyatakan, Informasi API: Judul, versi, lisensi, keamanan, server, tag, keamanan, dan dokumen eksternal. Untuk performa pembuatan dokumentasi yang lebih baik, deklarasikan anotasi @OpenAPIDefinition dan @SecurityScheme dalam kacang yang dikelola Spring.

dukungan spring-webflux dengan Pengontrol Beranotasi

• Dokumentasi juga dapat tersedia dalam format yaml, di jalur berikut: /v3/api-docs.yaml
• Tambahkan perpustakaan ke daftar dependensi proyek Anda (Tidak diperlukan konfigurasi tambahan)

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 '

• Langkah ini opsional: Untuk jalur khusus dokumentasi angkuh dalam format HTML, tambahkan properti springdoc khusus, di file konfigurasi spring-boot Anda:

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

Pustaka springdoc-openapi dihosting di repositori pusat maven. Artefak dapat dilihat diakses di lokasi berikut:

Rilis:

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

Jepretan:

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

Ucapan Terima Kasih

Kontributor

springdoc-openapi relevan dan diperbarui secara berkala karena kontribusi berharga dari kontributornya.

Terima kasih atas dukungan Anda!

Dukungan Tambahan

• Tim Musim Semi - Terima kasih atas dukungan mereka dengan membagikan semua sumber daya yang relevan seputar proyek Musim Semi.
• JetBrains - Terima kasih banyak telah mendukung proyek springdoc-openapi.