Anpassa OpenAPI-specifikationen
Lägg till metadata, servrar och säkerhetsscheman.
Anpassa OpenAPI-specifikationen är en gratis lektion i Spring Boot 4-mikrotjänster och REST API:er på CoddyKit. Detta är lektion 3 av 4. Ni kan läsa hela lektionen gratis nedan och sedan öva praktiskt i webbläsaren med en inbyggd kodredigerare och en AI-handledare som är tillgänglig dygnet runt. Den ingår i lärvägen för Spring Boot 4-mikrotjänster och REST API:er, och Era framsteg synkroniseras mellan webben och CoddyKit-appen. Kursen i Spring Boot 4-mikrotjänster och REST API:er innehåller totalt 4 lektioner.
Anpassa hela specifikationen
Utöver annoteringar per endpoint kan ni forma hela dokumentet – titel, version, kontakt, licens, servrar och säkerhet – genom att definiera en OpenAPI-bean.
Definiera en OpenAPI-bean
Returnera ett OpenAPI-objekt från en @Bean-metod, så använder SpringDoc det som grunddokument.
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("Orders API")
.version("v1")
.description("Public ordering service"));
}Info-sektionen
Info-objektet innehåller metadata som visas högst upp i Swagger UI: titel, version, beskrivning, användarvillkor, kontakt och licens.
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"));Deklarera servrar
Lista bas-URL:er där API:t kan nås. Swagger UI låter användarna välja server, och genererade klienter använder dessa som bassökvägar.
new OpenAPI()
.addServersItem(new Server().url("https://api.acme.com").description("Production"))
.addServersItem(new Server().url("http://localhost:8080").description("Local"));Varför servrar är viktiga bakom en proxy
När appen ligger bakom en gateway eller en context path kan den automatiskt upptäckta server-URL:en vara fel. Genom att deklarera servrar uttryckligen säkerställer ni att anrop från "Try it out" går till rätt adress.
Säkerhetsscheman
Dokumentera hur klienter autentiserar sig genom att registrera ett SecurityScheme i components, till exempel en bearer-JWT.
new OpenAPI()
.components(new Components()
.addSecuritySchemes("bearerAuth",
new SecurityScheme()
.type(SecurityScheme.Type.HTTP)
.scheme("bearer")
.bearerFormat("JWT")));Tillämpa säkerhet globalt
Lägg till ett SecurityRequirement så att gränssnittet visar en låsikon och låter användarna ange en token för alla skyddade operationer.
new OpenAPI()
.addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
.components(/* scheme defined above */);Säkerhet per operation
Om endast vissa endpoints ska skyddas använder ni @SecurityRequirement på controllermetoden i stället för att deklarera det globalt.
@SecurityRequirement(name = "bearerAuth")
@GetMapping("/admin/stats")
public Stats stats() { ... }Gruppera API:er med GroupedOpenApi
För stora appar kan ni dela upp dokumentationen i namngivna grupper, till exempel publika API:er och admin-API:er, med hjälp av GroupedOpenApi. Varje grupp kan ha egna sökvägsmatchare.
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("public")
.pathsToMatch("/public/**")
.build();
}Anpassa via properties
Vissa inställningar kan göras utan kod genom springdoc.*-properties – sortering av operationer, paket som ska genomsökas och vilka sökvägar som ska inkluderas.
# application.yml
springdoc:
packages-to-scan: com.acme.api
paths-to-match: /api/**
swagger-ui:
operations-sorter: methodOpenApiCustomizer för detaljerad kontroll
För programmatiska ändringar av varje operation implementerar ni en OpenApiCustomizer-bean och ändrar dokumentet efter genereringen – till exempel genom att lägga till en gemensam header för alla sökvägar.
Snabbkontroll
Testa era kunskaper om anpassning av specifikationen.
Sammanfattning
Ni har anpassat hela dokumentet:
- En
OpenAPI-bean angerInfo, servrar och säkerhet - Deklarera servrar för proxyservrar och context paths
SecurityScheme+SecurityRequirementdokumenterar autentiseringGroupedOpenApidelar upp stora API:er
Lär dig Java med en AI-lärare – gratis
Skriv och kör riktig kod i webbläsaren, få omedelbar hjälp av en AI-lärare dygnet runt och fortsätt där du slutade – på webben eller i appen.
- Kurser
- 24
- Lektioner
- 93
Vanliga frågor
Är lektionen ”Anpassa OpenAPI-specifikationen” gratis?
Ja – hela texten till ”Anpassa OpenAPI-specifikationen” kan läsas gratis här på webben. Om Ni vill öva interaktivt med en inbyggd kodredigerare och en AI-handledare som är tillgänglig dygnet runt och låsa upp resten av kursen i Spring Boot 4-mikrotjänster och REST API:er, kan Ni uppgradera till CoddyKit PRO. Kursen i Spring Boot 4-mikrotjänster och REST API:er innehåller totalt 4 lektioner.
Vad lär jag mig i ”Anpassa OpenAPI-specifikationen”?
Lägg till metadata, servrar och säkerhetsscheman. Ni övar på Spring Boot 4-mikrotjänster och REST API:er med praktisk kod som körs direkt i webbläsaren, medan en AI-handledare som är tillgänglig dygnet runt svarar på Era frågor under lektionen.
Behöver jag någon erfarenhet för att börja lära mig Spring Boot 4-mikrotjänster och REST API:er?
Du behöver inga förkunskaper. Utbildningen i Spring Boot 4-mikrotjänster och REST API:er på CoddyKit är upplagd för allt från nybörjare till avancerade elever, så att du kan börja här eller från början och gå fram i din egen takt. Detta är lektion 3 av 4.
Hur lång tid tar lektionen ”Anpassa OpenAPI-specifikationen”?
De flesta CoddyKit-lektioner tar cirka 5–10 minuter. Varje lektion är kort och interaktiv, så att du gör stadiga framsteg och kan fortsätta precis där du slutade – på webben eller i appen.
Kan jag skriva och köra kod i den här Spring Boot 4-mikrotjänster och REST API:er-lektionen?
Ja. Varje Spring Boot 4-mikrotjänster och REST API:er-lektion innehåller en inbyggd kodredigerare, så att du kan skriva och köra riktig kod direkt i webbläsaren och få omedelbar AI-feedback – utan lokal installation.
Alla lektioner i den här kursen
- Lägga till SpringDoc i projektet
- Dokumentera endpoints och modeller
- Anpassa OpenAPI-specifikationen
- Swagger UI