Triển Khai Swagger 3.0 Trên Spring Boot

Swagger 3.0, còn được biết đến với tên gọi OpenAPI 3.0, là một trong những công cụ hàng đầu hiện nay dùng để tài liệu hóa API. Đặc biệt trong các dự án Java Spring Boot, việc tài liệu hóa API là vô cùng quan trọng. Nó không chỉ giúp các nhà phát triển hiểu rõ cấu trúc và cách sử dụng API mà còn giúp đội ngũ kiểm thử dễ dàng kiểm tra và xác thực các chức năng của hệ thống. Swagger 3.0 cung cấp một giao diện người dùng tương tác (Swagger UI) giúp người dùng thử nghiệm và kiểm tra API một cách trực quan và dễ dàng.

Swagger

Hướng Dẫn Từng Bước Cài Đặt Và Cấu Hình Swagger 3.0 Trong Ứng Dụng Spring Boot

Bước 1: Thêm Dependencies

Thêm các dependencies cần thiết vào tệp pom.xml của dự án Spring Boot.

Dành cho Swagger 2.0:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.15</version>
</dependency>

Dành cho Swagger 3.0:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.3.0</version>
</dependency>

Bước 2: Cấu Hình Swagger

Tạo một lớp cấu hình cho Swagger trong dự án.

package com.example.demo.config;

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

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                    .title("Spring Boot Swagger Example API")
                    .version("1.0")
                    .description("This is a sample Spring Boot RESTful service using Swagger 3.")
                );
    }
}

Bước 3: Chạy Ứng Dụng Và Kiểm Tra

Khởi động ứng dụng Spring Boot và truy cập vào địa chỉ http://localhost:8080/swagger-ui.html để xem tài liệu API.

So Sánh Swagger 2 Và Swagger 3

Swagger 3.0 (OpenAPI 3.0) mang lại nhiều cải tiến so với Swagger 2, bao gồm:

Cấu Trúc Tài Liệu Tốt Hơn: OpenAPI 3.0 cung cấp cấu trúc tài liệu rõ ràng và dễ hiểu hơn.
Hỗ Trợ Tốt Hơn Cho Các Loại Dữ Liệu: OpenAPI 3.0 hỗ trợ nhiều loại dữ liệu phức tạp hơn, bao gồm oneOf, anyOf, và allOf.
Giao Diện Người Dùng Cải Tiến: Swagger UI trong OpenAPI 3.0 có nhiều tính năng mới và cải thiện hiệu suất.

Springdoc-OpenAPI Và Cách Tự Động Tạo Tài Liệu

Springdoc-openapi là một thư viện mạnh mẽ giúp tự động tạo tài liệu OpenAPI từ các annotations trong mã nguồn Spring Boot. Điều này giúp tiết kiệm thời gian và đảm bảo tài liệu API luôn cập nhật.

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@OpenAPIDefinition(info = @Info(title = "Spring Boot Swagger Example API", version = "1.0", description = "Spring Boot RESTful service using springdoc-openapi"))
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Sử Dụng Các Annotations Của Swagger Để Mô Tả API

Swagger cung cấp nhiều annotations để mô tả API, bao gồm các mô hình dữ liệu và phản hồi API.

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @Operation(summary = "Hello World API", responses = {
            @ApiResponse(description = "Successful Operation", responseCode = "200",
                    content = @Content(schema = @Schema(implementation = String.class)))})
    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

Tạo Tài Liệu API Đa Ngôn Ngữ Sử Dụng Swagger UI

Swagger UI hỗ trợ đa ngôn ngữ, giúp đội ngũ phát triển đa quốc gia dễ dàng truy cập và hiểu tài liệu API.

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                .title("Spring Boot Swagger Example API")
                .version("1.0")
                .description("This is a sample Spring Boot RESTful service using Swagger 3."))
            .externalDocs(new ExternalDocumentation()
                .description("Full API Documentation")
                .url("http://example.com/docs"));
}

Tích Hợp Swagger UI Vào Ứng Dụng Spring Boot Có Sẵn

Swagger UI có thể dễ dàng tích hợp vào ứng dụng Spring Boot hiện có, giúp cải thiện quá trình phát triển bằng cách cung cấp giao diện thử nghiệm API trực quan.

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

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                    .title("My API")
                    .version("1.0")
                    .description("API documentation using Swagger UI"));
    }
}

Ví Dụ Thực Tế Về Sử Dụng Swagger UI Để Kiểm Thử API

Swagger UI không chỉ giúp tài liệu hóa mà còn hỗ trợ kiểm thử API ngay trong quá trình phát triển. Người dùng có thể gửi yêu cầu trực tiếp từ giao diện và kiểm tra phản hồi từ máy chủ.

Kiểm Thử API

Truy cập http://localhost:8080/swagger-ui.html.
Chọn API cần kiểm thử.
Điền các thông số yêu cầu và nhấn “Execute”.
Xem kết quả phản hồi trực tiếp trên giao diện.

Phương Pháp Bảo Mật Cho Swagger UI Trong Môi Trường Production

Để bảo mật Swagger UI trong môi trường production, có thể cấu hình Spring Security để giới hạn quyền truy cập.

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            .antMatchers("/swagger-ui/**").authenticated()
            .and()
            .httpBasic();
    }
}

Kết Luận

Việc triển khai Swagger 3.0 mang lại nhiều lợi ích cho việc phát triển và bảo trì API trong các dự án Java Spring Boot. Từ việc tự động hóa quy trình tài liệu hóa, cải thiện giao tiếp trong đội ngũ phát triển, đến việc hỗ trợ kiểm thử và đảm bảo bảo mật, Swagger 3.0 là một công cụ không thể thiếu. Với những lợi ích này, việc áp dụng Swagger 3.0 chắc chắn sẽ nâng cao chất lượng và hiệu quả của các dự án phần mềm.