知識庫 / Spring RSS 訂閱

讓我們看看帶有註釋後的 HTML 文檔會是什麼樣子。 我們將看到元數據和應用於整個 API 的安全按鈕：

4. 控制器

現在我們已經配置了 Spring 框架和 springdoc-openapi 庫，讓我們在應用程序的基礎路徑中添加一個 REST 控制器。 要實現這一點，我們將使用 @RestController 和 @RequestMapping 註解：

@RestController
@RequestMapping("/")
public class DefaultGlobalSecuritySchemeOpenApiController {
    ...
}

之後，我們將定義兩個端點或 路徑。

第一個端點是 /login 端點。它將接收用户憑據並對用户進行身份驗證。如果身份驗證成功，端點將返回一個令牌。

API 的另一個端點是 /ping 端點，它需要 /login 方法生成的令牌。在執行請求之前，該方法會驗證令牌並檢查用户是否已授權。

總而言之，/login 端點對用户進行身份驗證並提供令牌。/ping 端點接收由/login 端點返回的令牌，並檢查其有效性以及用户是否可以執行操作。

4.1. login() 方法</h3

此方法將不具備任何安全要求。因此，我們需要覆蓋默認的安全配置要求

首先，我們需要告訴 Spring 這是一個 API 端點，因此我們將添加註解 @RequestMapping 以配置端點：

@RequestMapping(method = RequestMethod.POST, value = "/login", produces = { "application/json" }, consumes = { "application/json" })

之後，我們需要為端點添加語義信息。我們將使用 @Operation 和 @SecurityRequirements 註解。 @Operation 將定義端點，而 @SecurityRequirements 將定義適用於該端點的特定安全要求：

@Operation(operationId = "login", responses = {
    @ApiResponse(responseCode = "200", description = "api_key to be used in the secured-ping endpoint", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = TokenDto.class)) }),
    @ApiResponse(responseCode = "401", description = "Unauthorized request", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ApplicationExceptionDto.class)) }) })
@SecurityRequirements()

以下是翻譯後的內容：

例如，以下是帶有狀態碼 200 的響應的 HTML 文檔：

最後，讓我們查看 login() 方法的簽名：

public ResponseEntity login(@Parameter(name = "LoginDto", description = "Login") @Valid @RequestBody(required = true) LoginDto loginDto) {
    ...
}

如我們所見，API 請求的主體接收一個 LoginDto 實例。 此外，我們還需要使用語義信息來裝飾 DTO，以便在文檔中顯示相關信息：

public class LoginDto {
    private String user;
    private String pass;

    ...

    @Schema(name = "user", required = true)
    public String getUser() {
        return user;
    }

    @Schema(name = "pass", required = true)
    public String getPass() {
        return pass;
    }
}

這裏我們可以看到 /login 端點的 HTML 文檔將是什麼樣子:

4.2. ping() 方法

在此階段，我們將定義 ping() 方法。 ping() 方法將使用默認全局安全方案。

@Operation(operationId = "ping", responses = {
    @ApiResponse(responseCode = "200", description = "Ping that needs an api_key attribute in the header", content = {
        @Content(mediaType = "application/json", schema = @Schema(implementation = PingResponseDto.class), examples = { @ExampleObject(value = "{ pong: '2022-06-17T18:30:33.465+02:00' }") }) }),
    @ApiResponse(responseCode = "401", description = "Unauthorized request", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ApplicationExceptionDto.class)) }),
    @ApiResponse(responseCode = "403", description = "Forbidden request", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ApplicationExceptionDto.class)) }) })
@RequestMapping(method = RequestMethod.GET, value = "/ping", produces = { "application/json" })
public ResponseEntity ping(@RequestHeader(name = "api_key", required = false) String api_key) {
    ...
}

mvn spring-boot:run -Dstart-class="com.baeldung.defaultglobalsecurityscheme.DefaultGlobalSecuritySchemeApplication"