Perkhidmatan Mikro dan API REST Spring Boot 4 · Pelajaran

Menyesuaikan Spesifikasi OpenAPI

Tambah metadata, pelayan dan skema keselamatan.

Pelajaran 3 daripada 413 langkah

Menyesuaikan Spesifikasi OpenAPI ialah pelajaran Perkhidmatan Mikro dan API REST Spring Boot 4 percuma di CoddyKit. Ini ialah pelajaran 3 daripada 4. Anda boleh membaca keseluruhan pelajaran di bawah secara percuma — kemudian berlatih secara praktikal dalam pelayar menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran Perkhidmatan Mikro dan API REST Spring Boot 4, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus Perkhidmatan Mikro dan API REST Spring Boot 4 merangkumi sejumlah 4 pelajaran.

Menyesuaikan keseluruhan spesifikasi

Selain anotasi setiap titik akhir, anda boleh membentuk keseluruhan dokumen - tajuk, versi, kenalan, lesen, pelayan dan keselamatan - dengan mentakrifkan bean OpenAPI.

Mentakrifkan bean OpenAPI

Kembalikan objek OpenAPI daripada kaedah @Bean dan SpringDoc akan menggunakannya sebagai dokumen asas.

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                .title("Orders API")
                .version("v1")
                .description("Public ordering service"));
}

Bahagian maklumat

Objek Info menyimpan metadata yang dipaparkan di bahagian atas UI Swagger: tajuk, versi, penerangan, terma perkhidmatan, kenalan dan lesen.

new Info()
    .title("Orders API")
    .version("1.2.0")
    .contact(new Contact().name("API Team").email("api@acme.com"))
    .license(new License().name("Apache 2.0").url("https://apache.org/licenses/LICENSE-2.0"));

Mengisytiharkan pelayan

Senaraikan URL asas tempat API boleh dicapai. UI Swagger membolehkan pengguna memilih pelayan, dan klien yang dijana menggunakan URL ini sebagai laluan asas.

new OpenAPI()
    .addServersItem(new Server().url("https://api.acme.com").description("Production"))
    .addServersItem(new Server().url("http://localhost:8080").description("Local"));

Mengapa pelayan penting di belakang proksi

Apabila aplikasi anda berada di belakang get laluan atau laluan konteks, URL pelayan yang dikesan secara automatik mungkin salah. Pengisytiharan pelayan secara jelas memastikan panggilan "Cuba" dihantar ke alamat yang betul.

Skema keselamatan

Dokumenkan cara klien mengesahkan identiti dengan mendaftarkan SecurityScheme dalam komponen, contohnya JWT bearer.

new OpenAPI()
    .components(new Components()
        .addSecuritySchemes("bearerAuth",
            new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")));

Menggunakan keselamatan secara global

Tambahkan SecurityRequirement supaya UI memaparkan ikon kunci dan membolehkan pengguna membekalkan token untuk semua operasi yang dilindungi.

new OpenAPI()
    .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
    .components(/* scheme defined above */);

Keselamatan bagi setiap operasi

Untuk melindungi hanya beberapa titik akhir, gunakan @SecurityRequirement pada kaedah controller dan bukannya mengisytiharkannya secara global.

@SecurityRequirement(name = "bearerAuth")
@GetMapping("/admin/stats")
public Stats stats() { ... }

Mengumpulkan API dengan GroupedOpenApi

Untuk aplikasi besar, anda boleh memisahkan dokumentasi kepada kumpulan bernama (contohnya awam berbanding pentadbir) menggunakan GroupedOpenApi, setiap satunya dengan pemadan laluan sendiri.

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/public/**")
            .build();
}

Menyesuaikan melalui sifat

Sesetengah tetapan boleh dibuat tanpa kod melalui sifat springdoc.* - pengisihan operasi, pakej untuk diimbas dan laluan yang perlu disertakan.

# application.yml
springdoc:
  packages-to-scan: com.acme.api
  paths-to-match: /api/**
  swagger-ui:
    operations-sorter: method

OpenApiCustomizer untuk kawalan terperinci

Untuk pelarasan berprogram pada setiap operasi, laksanakan bean OpenApiCustomizer dan ubah dokumen selepas penjanaan - contohnya menambah pengepala umum pada semua laluan.

Semakan ringkas

Uji pemahaman anda tentang penyesuaian spesifikasi.

Jawab dalam pelajaran interaktif

Imbas kembali

Anda telah menyesuaikan keseluruhan dokumen:

Bean OpenAPI menetapkan Info, pelayan dan keselamatan
Isytiharkan pelayan untuk proksi/laluan konteks
SecurityScheme + SecurityRequirement mendokumenkan pengesahan
GroupedOpenApi memisahkan API yang besar

Percuma untuk bermula

Pelajari Java dengan tutor kecerdasan buatan — percuma

Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.

Kursus: 24
Pelajaran: 93

Mula belajar secara percuma Lihat kursus penuh

Soalan Lazim

Adakah pelajaran “Menyesuaikan Spesifikasi OpenAPI” percuma?

Ya — teks penuh “Menyesuaikan Spesifikasi OpenAPI” boleh dibaca secara percuma di web ini. Untuk berlatih secara interaktif menggunakan penyunting kod terbina dalam dan tutor kecerdasan buatan 24/7, serta membuka kunci baki kursus Perkhidmatan Mikro dan API REST Spring Boot 4, tingkat taraf kepada CoddyKit PRO. Kursus Perkhidmatan Mikro dan API REST Spring Boot 4 merangkumi sejumlah 4 pelajaran.

Apakah yang akan saya pelajari dalam “Menyesuaikan Spesifikasi OpenAPI”?

Tambah metadata, pelayan dan skema keselamatan. Anda berlatih Perkhidmatan Mikro dan API REST Spring Boot 4 menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.

Adakah saya memerlukan pengalaman untuk memulakan Perkhidmatan Mikro dan API REST Spring Boot 4?

Tiada pengalaman terdahulu diperlukan. Pembelajaran Perkhidmatan Mikro dan API REST Spring Boot 4 di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 3 daripada 4.

Berapa lamakah pelajaran “Menyesuaikan Spesifikasi OpenAPI” diambil?

Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.

Bolehkah saya menulis dan menjalankan kod dalam pelajaran Perkhidmatan Mikro dan API REST Spring Boot 4 ini?

Ya. Setiap pelajaran Perkhidmatan Mikro dan API REST Spring Boot 4 menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.

Semua pelajaran dalam kursus ini

← Kembali ke Perkhidmatan Mikro dan API REST Spring Boot 4