Dostosowywanie specyfikacji OpenAPI
Dodawaj metadane, serwery i schematy zabezpieczeń
Dostosowywanie specyfikacji OpenAPI to bezpłatna lekcja Spring Boot 4 Microservices & REST APIs na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Spring Boot 4 Microservices & REST APIs, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Spring Boot 4 Microservices & REST APIs zawiera 4 lekcji w sumie.
Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.
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: methodOpenApiCustomizer 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
OpenAPIbean setsInfo, servers and security - Declare servers for proxies/context paths
SecurityScheme+SecurityRequirementdocument authGroupedOpenApisplits large APIs
Ucz się Java dzięki korepetycjom AI — za darmo
Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.
- Kursy
- 24
- Lekcje
- 93
Często zadawane pytania
Czy lekcja „Dostosowywanie specyfikacji OpenAPI” jest bezpłatna?
Tak — pełny tekst „Dostosowywanie specyfikacji OpenAPI” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Spring Boot 4 Microservices & REST APIs, przejdź na CoddyKit PRO. Kurs Spring Boot 4 Microservices & REST APIs zawiera 4 lekcji w sumie.
Co nauczysz się w „Dostosowywanie specyfikacji OpenAPI”?
Dodawaj metadane, serwery i schematy zabezpieczeń Ćwiczysz Spring Boot 4 Microservices & REST APIs z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć Spring Boot 4 Microservices & REST APIs?
Nie wymagamy żadnego doświadczenia. Spring Boot 4 Microservices & REST APIs w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.
Ile czasu zajmuje lekcja „Dostosowywanie specyfikacji OpenAPI”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji Spring Boot 4 Microservices & REST APIs?
Tak. Każda lekcja Spring Boot 4 Microservices & REST APIs zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Dodawanie SpringDoc do projektu
- Dokumentowanie endpointów i modeli
- Dostosowywanie specyfikacji OpenAPI
- Swagger UI