Spring Boot 4 Microservices & REST APIs · Aula

Personalizando a especificação OpenAPI

Adicione metadados, servidores e esquemas de segurança.

Personalizando a especificação OpenAPI é uma aula grátis de Spring Boot 4 Microservices & REST APIs no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Spring Boot 4 Microservices & REST APIs, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Spring Boot 4 Microservices & REST APIs inclui 4 aulas no total.

Partes desta aula ainda não foram traduzidas e aparecem em 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

Perguntas Frequentes

A aula “Personalizando a especificação OpenAPI” é grátis?

Sim — o texto completo de “Personalizando a especificação OpenAPI” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Spring Boot 4 Microservices & REST APIs, atualize para CoddyKit PRO. O curso de Spring Boot 4 Microservices & REST APIs inclui 4 aulas no total.

O que vou aprender em “Personalizando a especificação OpenAPI”?

Adicione metadados, servidores e esquemas de segurança. Você pratica Spring Boot 4 Microservices & REST APIs com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Spring Boot 4 Microservices & REST APIs?

Nenhuma experiência prévia é necessária. Spring Boot 4 Microservices & REST APIs no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Personalizando a especificação OpenAPI”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Spring Boot 4 Microservices & REST APIs?

Sim. Cada aula de Spring Boot 4 Microservices & REST APIs inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Spring Boot 4 Microservices & REST APIs