在這篇文章中，我們將探索如何在 Spring Boot 應(yīng)用程式中設(shè)定 OpenAPI，並新增從根 URL 到 Swagger UI 的便利重定向。此設(shè)定將改進您的 API 文件並使其更易於開發(fā)人員存取。

OpenAPI Bean 配置

首先，讓我們建立一個設(shè)定類別來自訂我們的 OpenAPI 文件：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.boot.info.GitProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI(GitProperties gitProperties) {
        return new OpenAPI()
                .info(new Info()
                        .title("Book Catalog API")
                        .description("REST API for managing a book catalog. Application version: "+ gitProperties.get("build.version"))
                        .version("1.0.0")
                        .contact(new Contact()
                                .name("Book Catalog Team")
                                .email("support@bookcatalog.com")
                                .url("https://github.com/vlaship/book-catalog"))
                        .license(new License()
                                .name("MIT License")
                                .url("https://opensource.org/licenses/MIT"))
                );
    }
}

此組態(tài)建立一個自訂 OpenAPI bean，其中包含有關(guān)您的 API 的基本資訊。您可以透過新增更多詳細資訊（例如聯(lián)絡(luò)資訊、授權(quán)或外部文件）來進一步自訂。
我們可以使用 GitProperties 來提供更多詳細資訊。

根 URL 重新導(dǎo)向控制器

接下來，讓我們建立一個控制器來將使用者從根 URL 重新導(dǎo)向到 Swagger UI：

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class OpenApiController {
    @GetMapping("/")
    public String index() {
        return "redirect:swagger-ui.html";
    }
}

這個簡單的控制器使用 @GetMapping 作為根 URL（“/”）並重定向到 Swagger UI HTML 頁面。

更新 application.yaml

此設(shè)定檔通常名為 application.yml，在定義應(yīng)用程式行為的各個方面起著至關(guān)重要的作用。

spring:
  application:
    name: book-catalog
    version: '@project.version@'
  mvc:
    problemdetails:
      enabled: true

management:
  endpoints:
    web:
      exposure:
        include: '*'
  info:
    git:
      mode: full

server:
  port: 8888
  servlet:
    context-path: /${spring.application.name}
  error:
    whitelabel:
      enabled: false

提供的 YAML 設(shè)定涵蓋了 Spring Boot 應(yīng)用程式的幾個關(guān)鍵領(lǐng)域：

1. 應(yīng)用程式屬性：

name：定義應(yīng)用程式的名稱，這裡設(shè)定為 book-catalog。

版本：引用可能在建置過程中填入的佔位符，以指定應(yīng)用程式的版本。

1. MVC 配置：

problemdetails.enabled：在異?；貞?yīng)正文中啟用詳細問題報告。

1. 管理端點：

endpoints.web.exposure.include: '*':** 公開所有執(zhí)行器端點以用於監(jiān)視和管理目的。

info.git.mode: full：在 /info 端點提供詳細的 Git 資訊。

1. 伺服器設(shè)定：

port：設(shè)定伺服器監(jiān)聽傳入請求的連接埠（預(yù)設(shè)8080，這裡設(shè)定為8888）。

servlet.context-path：定義應(yīng)用程式的上下文路徑，確保請求正確路由。

error.whitelabel.enabled: false：停用預(yù)設(shè)的白標(biāo)籤錯誤頁面，以便在開發(fā)過程中提供更多資訊性錯誤訊息。

新增banner.txt

1。建立banner.txt檔案

在 Spring Boot 專案的 src/main/resources 目錄中建立一個名為 Banner.txt 的新檔案。

2。將服務(wù)詳細資訊加入banner.txt

您可以將任何文字或 ASCII 藝術(shù)添加到此文件中。這是一個例子：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.boot.info.GitProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI(GitProperties gitProperties) {
        return new OpenAPI()
                .info(new Info()
                        .title("Book Catalog API")
                        .description("REST API for managing a book catalog. Application version: "+ gitProperties.get("build.version"))
                        .version("1.0.0")
                        .contact(new Contact()
                                .name("Book Catalog Team")
                                .email("support@bookcatalog.com")
                                .url("https://github.com/vlaship/book-catalog"))
                        .license(new License()
                                .name("MIT License")
                                .url("https://opensource.org/licenses/MIT"))
                );
    }
}

這種方法為您的應(yīng)用程式啟動增添了專業(yè)感，並一目了然地提供有價值的資訊。

新增 Dockerfile

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class OpenApiController {
    @GetMapping("/")
    public String index() {
        return "redirect:swagger-ui.html";
    }
}

圖層擷?。?/strong>為依賴項建立單獨的圖層，提高建置效率並減少影像大小更新。
多階段建置：利用多階段建置流程將建置環(huán)境與執(zhí)行時間環(huán)境分開，產(chǎn)生較小、更有效率的最終影像。
輕量級基礎(chǔ)鏡像： 使用像 azul/zulu-openjdk-alpine:21-jre-headless 這樣的最小基礎(chǔ)鏡像來進一步減少鏡像大小。