0Pricing
Spring Boot 4 Microservices & REST APIs · Lección

Personalizar la especificación de OpenAPI

Añada metadatos, servidores y esquemas de seguridad

Personalizar la especificación de OpenAPI es una lección gratuita de Spring Boot 4 Microservices & REST APIs en CoddyKit. Esta es la lección 3 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Spring Boot 4 Microservices & REST APIs, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Spring Boot 4 Microservices & REST APIs incluye 4 lecciones en total.

Partes de esta lección aún no han sido traducidas y se muestran en inglés.

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

Preguntas frecuentes

¿La lección «Personalizar la especificación de OpenAPI» es gratis?

Sí — el texto completo de «Personalizar la especificación de OpenAPI» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Spring Boot 4 Microservices & REST APIs, actualiza a CoddyKit PRO. El curso de Spring Boot 4 Microservices & REST APIs incluye 4 lecciones en total.

¿Qué aprenderé en «Personalizar la especificación de OpenAPI»?

Añada metadatos, servidores y esquemas de seguridad Practicas Spring Boot 4 Microservices & REST APIs con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Spring Boot 4 Microservices & REST APIs?

No se requiere experiencia previa. Spring Boot 4 Microservices & REST APIs en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 3 de 4.

¿Cuánto tiempo toma la lección «Personalizar la especificación de OpenAPI»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Spring Boot 4 Microservices & REST APIs?

Sí. Cada lección de Spring Boot 4 Microservices & REST APIs incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Añadir SpringDoc a su proyecto
  2. Documentar endpoints y modelos
  3. Personalizar la especificación de OpenAPI
  4. Swagger UI
← Volver a Spring Boot 4 Microservices & REST APIs