Microservices e-commerce #5: tài liệu API với OpenAPI và Swagger UI

dependencies {
    implementation project(':util')
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'org.springframework.boot:spring-boot-starter-webflux'
    implementation "org.springdoc:springdoc-openapi-starter-webflux-ui:${springdocVersion}"
    // ...
}

@SpringBootApplication
@ComponentScan("com.ecommerce")
public class ProductCompositeServiceApplication {

    @Value("${api.common.version}") String apiVersion;
    @Value("${api.common.title}") String apiTitle;
    @Value("${api.common.description}") String apiDescription;
    @Value("${api.common.license}") String apiLicense;
    @Value("${api.common.licenseUrl}") String apiLicenseUrl;
    @Value("${api.common.externalDocDesc}") String apiExternalDocDesc;
    @Value("${api.common.externalDocUrl}") String apiExternalDocUrl;
    @Value("${api.common.contact.name}") String apiContactName;
    @Value("${api.common.contact.url}") String apiContactUrl;

    /** Thông tin chung của API, hiển thị ở đầu trang Swagger UI. */
    @Bean
    public OpenAPI getOpenApiDocumentation() {
        return new OpenAPI()
            .info(new Info().title(apiTitle)
                .description(apiDescription)
                .version(apiVersion)
                .contact(new Contact().name(apiContactName).url(apiContactUrl))
                .license(new License().name(apiLicense).url(apiLicenseUrl)))
            .externalDocs(new ExternalDocumentation()
                .description(apiExternalDocDesc)
                .url(apiExternalDocUrl));
    }

    public static void main(String[] args) {
        SpringApplication.run(ProductCompositeServiceApplication.class, args);
    }
}

package com.ecommerce.api.composite.product;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import reactor.core.publisher.Mono;

@Tag(name = "ProductComposite", description = "REST API cho trang chi tiết sản phẩm (catalog + review + gợi ý).")
public interface ProductCompositeService {

    @Operation(
        summary = "${api.product-composite.get-composite-product.description}",
        description = "${api.product-composite.get-composite-product.notes}")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "${api.responseCodes.ok.description}"),
        @ApiResponse(responseCode = "400", description = "${api.responseCodes.badRequest.description}"),
        @ApiResponse(responseCode = "404", description = "${api.responseCodes.notFound.description}"),
        @ApiResponse(responseCode = "422", description = "${api.responseCodes.unprocessableEntity.description}")
    })
    @GetMapping(value = "/product-composite/{productId}", produces = "application/json")
    Mono<ProductAggregate> getProduct(@PathVariable int productId);
}

springdoc:
  swagger-ui.path: /openapi/swagger-ui.html
  api-docs.path: /openapi/v3/api-docs
  packagesToScan: com.ecommerce.composite.product
  pathsToMatch: /**

api:
  common:
    version: 1.0.0
    title: E-commerce Platform API
    description: API của trang chi tiết sản phẩm, dựng theo sách Microservices with Spring Boot 3 and Spring Cloud.
    license: Apache 2.0
    licenseUrl: https://www.apache.org/licenses/LICENSE-2.0
    externalDocDesc: Series bài viết trên blog
    externalDocUrl: https://hoangluongtran.dev/
    contact:
      name: Hoàng Lương Trần
      url: https://hoangluongtran.dev/

  responseCodes:
    ok.description: OK
    badRequest.description: Request sai định dạng, xem message để biết chi tiết
    notFound.description: Không tìm thấy, xem message để biết chi tiết
    unprocessableEntity.description: Dữ liệu đầu vào không hợp lệ, xem message để biết chi tiết

  product-composite:
    get-composite-product:
      description: Lấy thông tin tổng hợp của một sản phẩm theo productId
      notes: |
        # Mô tả
        Trả về thông tin sản phẩm cùng danh sách gợi ý và đánh giá.

        # Dữ liệu giả lập (cho tới bài 6)
        1. productId 13 trả về 404 Not Found
        1. productId 113 không có gợi ý nào
        1. productId 213 không có đánh giá nào
        1. productId âm trả về 422 Unprocessable Entity
        1. productId không phải số trả về 400 Bad Request

./gradlew build
docker compose build
docker compose up -d

$ curl -s localhost:8080/openapi/v3/api-docs.yaml | head -20
openapi: 3.1.0
info:
  title: E-commerce Platform API
  description: "API của trang chi tiết sản phẩm, dựng theo sách Microservices with\
    \ Spring Boot 3 and Spring Cloud."
  contact:
    name: Hoàng Lương Trần
    url: https://hoangluongtran.dev/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0
externalDocs:
  description: Series bài viết trên blog
  url: https://hoangluongtran.dev/
servers:
- url: http://localhost:8080
  description: Generated server url
tags:
- name: ProductComposite
  description: REST API cho trang chi tiết sản phẩm (catalog + review + gợi ý).

# Swagger UI và tài liệu OpenAPI
assertCurl 302 "curl -s http://$HOST:$PORT/openapi/swagger-ui.html"
assertCurl 200 "curl -sL http://$HOST:$PORT/openapi/swagger-ui.html"
assertCurl 200 "curl -s http://$HOST:$PORT/openapi/swagger-ui/index.html"
assertCurl 200 "curl -s http://$HOST:$PORT/openapi/v3/api-docs"
assertEqual "1.0.0" "$(echo $RESPONSE | jq -r .info.version)"
assertEqual "http://$HOST:$PORT" "$(echo $RESPONSE | jq -r .servers[].url)"
assertCurl 200 "curl -s http://$HOST:$PORT/openapi/v3/api-docs.yaml"

$ ./test-em-all.bash start stop
...
Test OK (HTTP Code: 302)
Test OK (HTTP Code: 200)
Test OK (HTTP Code: 200)
Test OK (HTTP Code: 200)
Test OK (actual value: 1.0.0)
Test OK (actual value: http://localhost:8080)
Test OK (HTTP Code: 200)
We are done, stopping the test environment...
End, all tests OK: Fri Oct 2 06:01:51 UTC 2026

git add .
git commit -m "Bài 5: OpenAPI và Swagger UI"
git tag blog-05