Panduan ini menunjukkan penyepaduan Swagger 3 (OpenAPI) dengan Spring Cloud Gateway untuk dokumentasi API perkhidmatan mikro yang diperkemas. Kami akan memanfaatkan Java 21, Spring Boot 3.2 dan Micronaut untuk mencipta penyelesaian yang mantap dan mesra pengguna.

Mengapa Pilih Swagger/OpenAPI?

Swagger, kini Spesifikasi OpenAPI (OAS), ialah piawaian dokumentasi API terkemuka. Khasiatnya termasuklah:

• Standard Industri: Diguna pakai secara meluas dan disokong oleh ekosistem alatan yang kaya.
• Dokumentasi Interaktif: Menjana dokumentasi mesra pengguna yang membolehkan pembangun meneroka dan menguji API secara langsung.
• Produktiviti Pembangun yang Dipertingkat: Ciri seperti penjanaan kod untuk SDK dan stub pelayan mempercepatkan pembangunan API.
• Kolaborasi Dipertingkat: Memberikan pemahaman bersama tentang fungsi API untuk pembangun, penguji dan pihak berkepentingan.
• Pengujian dan Nyahpepijat Ringkas: UI Swagger termasuk antara muka ujian untuk mengesahkan respons API.
• Sokongan Merentas Bahasa: Bersepadu dengan lancar merentas susunan teknologi yang pelbagai.
• Penyepaduan Mudah: Penyepaduan mudah dengan rangka kerja popular seperti Spring Boot dan Micronaut.
• Mesra Automasi: Menyokong automasi untuk pengurusan kitaran hayat API.
• Sumber Terbuka dengan Pilihan Perusahaan: Tersedia sebagai alat sumber terbuka percuma dengan pilihan perusahaan.

Spring Cloud Gateway: The Foundation

Spring Cloud Gateway, dibina pada Spring Framework 5, Spring Boot 2 dan Project Reactor, bertindak sebagai titik masuk pusat untuk penghalaan dan penapisan permintaan kepada perkhidmatan mikro anda.

Bagaimana Spring Cloud Gateway Berfungsi:

Rajah di bawah menggambarkan operasi Spring Cloud Gateway:

Permintaan pelanggan dinilai berdasarkan laluan yang ditetapkan. Permintaan padanan diproses oleh Pengendali Web Gateway, melaksanakan penapisan pra dan pasca sebelum dan selepas meminta proksi.

Membina Aplikasi:

Prasyarat:

1. Jawa 21
2. Gradle (atau Maven)
3. Spring Boot 3.2 atau lebih baru
4. Pemahaman Spring Cloud Gateway dan Swagger
5. Micronaut

Pelaksanaan Langkah demi Langkah:

Langkah 1: Buat Aplikasi Micronaut (Pekerjaan, Perk, Perkhidmatan Tag)

Gunakan Pelancar Micronaut ([pautan ke pelancar]) untuk mencipta tiga aplikasi Micronaut: job-service, perk-service dan tag-service. Pilih Java atau Kotlin, versi Micronaut stabil terkini, Swagger UI dan OpenAPI sebagai ciri. Gunakan Gradle atau Maven sebagai alat binaan. Setiap perkhidmatan akan mempunyai UI Swagger yang boleh diakses (mis., http://localhost:8081/swagger-ui/index.html untuk job-service). Anda juga boleh menggunakan CLI:

mn create-app --build=gradle_kotlin --jdk=21 --lang=java --test=junit --features=openapi,swagger-ui dev.job.job

(Ulang untuk perk-service dan tag-service, laraskan nama pakej dengan sewajarnya).

Langkah 2: Buat Gerbang API Spring Boot

Gunakan Spring Initializr ([pautan ke Spring Initializr]) untuk menjana projek Spring Boot. Sertakan kebergantungan berikut: Spring Cloud Gateway, Spring Boot Actuator dan Spring Web.

Langkah 3: Sepadukan Swagger ke dalam Gerbang API

Tambahkan kebergantungan Springdoc yang diperlukan pada pom.xml (Maven) atau build.gradle (Gradle) anda:

dependencies {
    implementation("org.springframework.cloud:spring-cloud-starter-gateway")
    implementation("org.springdoc:springdoc-openapi-starter-webmvc-api:2.8.3")
    implementation("org.springdoc:springdoc-openapi-starter-webflux-ui:2.8.3")
}

Konfigurasikan application.yml untuk mendayakan UI Swagger dan nyatakan URL untuk setiap fail Swagger YAML perkhidmatan mikro:

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    config-url: /v3/api-docs/swagger-config
    urls:
      - name: Job Service
        url: http://localhost:8081/swagger/job-service-0.0.yml
      - name: Perk Service
        url: http://localhost:8082/swagger/perk-0.0.yml
      - name: Tag Service
        url: http://localhost:8083/swagger/tag-0.0.yml

Tetapkan port Gateway API kepada 8080 dalam application.yml:

server:
  port: 8080
spring:
  application:
    name: web-api-gateway

Langkah 4: Jalankan Aplikasi

Mulakan setiap satu daripada empat aplikasi (tiga perkhidmatan Micronaut dan Spring Boot Gateway). UI Swagger Gateway boleh diakses di http://localhost:8080/webjars/swagger-ui/index.html.

Kesimpulan:

Pendekatan gabungan ini menyediakan seni bina perkhidmatan mikro yang berkuasa dan didokumentasikan dengan baik. Spring Cloud Gateway dengan cekap mengarahkan permintaan, manakala Swagger menawarkan pengalaman dokumentasi API terpusat dan interaktif. Persediaan ini meningkatkan produktiviti dan kerjasama pembangun dengan ketara. Ingat untuk menggantikan URL pemegang tempat dengan URL sebenar fail Swagger YAML perkhidmatan mikro anda.

Atas ialah kandungan terperinci Agregat Microservices&# Swagger UI daripada API Gateway Menggunakan Spring API Gateway dan Micronaut. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!