Spring Boot 4 Microservices & REST APIs · درس

تخصيص مواصفات OpenAPI

أضف البيانات الوصفية والخوادم ومخططات الأمان

تخصيص مواصفات OpenAPI درس مجاني في Spring Boot 4 Microservices & REST APIs على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Spring Boot 4 Microservices & REST APIs، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Spring Boot 4 Microservices & REST APIs 4 دروس في المجموع.

بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.

Customizing the whole spec

Beyond per-endpoint annotations, you can shape the entire document - title, version, contact, license, servers and security - by defining an OpenAPI bean.

Defining an OpenAPI bean

Return an OpenAPI object from a @Bean method and SpringDoc uses it as the base document.

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

The info section

The Info object holds metadata shown at the top of Swagger UI: title, version, description, terms of service, contact and license.

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"));

Declaring servers

List the base URLs where the API is reachable. Swagger UI lets users pick a server, and generated clients use these as base paths.

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

Why servers matter behind a proxy

When your app sits behind a gateway or context path, the auto-detected server URL can be wrong. Declaring servers explicitly ensures "Try it out" calls hit the correct address.

Security schemes

Document how clients authenticate by registering a SecurityScheme in the components, e.g. a bearer JWT.

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

Applying security globally

Add a SecurityRequirement so the UI shows a lock icon and lets users supply a token for all secured operations.

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

Per-operation security

To secure only some endpoints, use @SecurityRequirement on the controller method instead of declaring it globally.

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

Grouping APIs with GroupedOpenApi

For large apps you can split docs into named groups (e.g. public vs admin) using GroupedOpenApi, each with its own path matchers.

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

Customizing via properties

Some settings can be done without code through springdoc.* properties - sorting operations, packages to scan, and which paths to include.

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

OpenApiCustomizer for fine control

For programmatic tweaks to every operation, implement an OpenApiCustomizer bean and mutate the document after generation - e.g. add a common header to all paths.

Quick Check

Test your spec-customization understanding.

Recap

You customized the whole document:

An OpenAPI bean sets Info, servers and security
Declare servers for proxies/context paths
SecurityScheme + SecurityRequirement document auth
GroupedOpenApi splits large APIs

الأسئلة الشائعة

هل درس «تخصيص مواصفات OpenAPI» مجاني؟

نعم — نص درس «تخصيص مواصفات OpenAPI» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Spring Boot 4 Microservices & REST APIs، انتقل إلى CoddyKit PRO. تتضمن دورة Spring Boot 4 Microservices & REST APIs 4 دروس في المجموع.

ماذا ستتعلم في «تخصيص مواصفات OpenAPI»؟

أضف البيانات الوصفية والخوادم ومخططات الأمان تتمرن على Spring Boot 4 Microservices & REST APIs مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Spring Boot 4 Microservices & REST APIs؟

لا تُشترط خبرة سابقة. Spring Boot 4 Microservices & REST APIs على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «تخصيص مواصفات OpenAPI»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Spring Boot 4 Microservices & REST APIs هذا؟

نعم. كل درس في Spring Boot 4 Microservices & REST APIs يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Spring Boot 4 Microservices & REST APIs