SBA301 - Chương 9: Tài liệu hoá API với OpenAPI và Swagger

Trong tài liệu REST của Spring, các yếu tố quan trọng thường được tìm thấy bao gồm phương thức HTTP (ví dụ: GET, POST), URL endpoint, và dữ liệu yêu cầu và phản hồi. Tuy nhiên, cấu trúc cơ sở dữ liệu ẩn dưới (the underlying database schema) không phải là một phần quan trọng trong tài liệu REST của Spring. Điều này là vì tài liệu REST thường tập trung vào giao diện và hành vi của API, chứ không phải là chi tiết về cơ sở dữ liệu.

Để ghi chép các phản hồi khả năng xảy ra khác nhau cho một điểm cuối, chẳng hạn như 200 OK hoặc 404 Not Found, bạn có thể sử dụng các annotation @ApiResponses và @ApiResponse trên phương thức controller. Các annotation này cho phép bạn mô tả các phản hồi khả năng xảy ra khác nhau cho một điểm cuối, bao gồm cả mã trạng thái HTTP và mô tả của phản hồi. Điều này giúp cho việc sử dụng và hiểu rõ về điểm cuối trở nên dễ dàng hơn.

Để nhóm các điểm cuối API liên quan trong Swagger 3, bạn có thể sử dụng thuộc tính tags trong @Tag annotations. Các điểm cuối API có cùng mục đích hoặc chức năng có thể được nhóm lại dưới cùng một thẻ (tag). Ví dụ, bạn có thể tạo một thẻ cho các điểm cuối API liên quan đến quản lý người dùng, một thẻ cho các điểm cuối API liên quan đến quản lý sản phẩm, v.v. Điều này giúp người dùng dễ dàng tìm kiếm và hiểu được chức năng của từng điểm cuối API.

Để mô tả nội dung của request body trong một hoạt động OpenAPI, bạn cần sử dụng annotation nào? Các lựa chọn bao gồm @ApiBody, @RequestContent, @RequestBody (từ gói swagger) và @RequestDoc. Annotation @RequestBody (từ gói swagger) là lựa chọn đúng. Nó được sử dụng để mô tả nội dung của request body, bao gồm cả dữ liệu JSON, XML hoặc các định dạng khác. Annotation này cho phép bạn định nghĩa cấu trúc của dữ liệu request body, bao gồm các trường và loại dữ liệu của chúng. Điều này giúp cho việc phát triển và kiểm tra API trở nên dễ dàng hơn.

Để thay đổi mặc định địa chỉ OpenAPI endpoint trong ứng dụng Spring, bạn cần sử dụng thuộc tính cấu hình Spring. Trong các lựa chọn trên, thuộc tính "springdoc.api-docs.path" là lựa chọn đúng. Nó cho phép bạn thay đổi địa chỉ mặc định của OpenAPI endpoint, giúp bạn có thể tùy chỉnh và quản lý API của mình một cách linh hoạt hơn. Ví dụ, bạn có thể sử dụng thuộc tính này để thay đổi địa chỉ OpenAPI endpoint thành một địa chỉ khác, chẳng hạn như "/api/docs" hoặc "/swagger".

Để nhóm các API trong Swagger UI bằng cách sử dụng Springdoc OpenAPI, bạn có thể sử dụng một số cách khác nhau. Một trong những cách phổ biến nhất là sử dụng @Tag. @Tag cho phép bạn tạo ra các nhóm API dựa trên các thuộc tính như tên nhóm, mô tả nhóm, v.v. Ví dụ, bạn có thể tạo một nhóm API có tên là 'GroupName' bằng cách sử dụng @Tag như sau: @Tag(name = 'GroupName'). Sau đó, bạn có thể sử dụng @Operation để thêm các phương thức API vào nhóm này. Ngoài ra, bạn cũng có thể sử dụng @Api để tạo ra các nhóm API có tên và mô tả. Tuy nhiên, cách sử dụng @Tag là phổ biến nhất và được khuyến khích sử dụng.

Trong Spring Boot, có nhiều tùy chọn để tích hợp OpenAPI 3. Tuy nhiên, tùy chọn phổ biến nhất là sử dụng springdoc-openapi-ui. Đây là một thư viện mở nguồn cung cấp một số tính năng mạnh mẽ để tạo và quản lý API, bao gồm việc tạo tài liệu OpenAPI, tạo giao diện người dùng và hỗ trợ tích hợp với các công cụ khác. Để sử dụng springdoc-openapi-ui trong dự án Spring Boot của mình, bạn cần thêm dependency vào file pom.xml (nếu bạn đang sử dụng Maven) hoặc build.gradle (nếu bạn đang sử dụng Gradle). Sau đó, bạn có thể cấu hình và sử dụng các tính năng của springdoc-openapi-ui để tạo và quản lý API của mình.

Để ẩn một endpoint khỏi tài liệu OpenAPI, bạn có thể sử dụng một số cách khác nhau. Một trong những cách phổ biến nhất là sử dụng annotation @Hidden. Annotation này cho phép bạn ẩn một phương thức hoặc một endpoint khỏi tài liệu OpenAPI mà không cần phải xóa hoặc sửa đổi mã nguồn. Điều này rất hữu ích khi bạn muốn ẩn một endpoint chỉ dành cho mục đích nội bộ hoặc để bảo vệ thông tin nhạy cảm. Ngoài ra, bạn cũng có thể sử dụng cách khác như Disable controller hoặc Rename method, nhưng cách này có thể phức tạp hơn và không được khuyến khích sử dụng. Vì vậy, cách tốt nhất để ẩn một endpoint khỏi tài liệu OpenAPI là sử dụng annotation @Hidden.

Swagger 3 (OpenAPI 3) là một tiêu chuẩn mở cho việc mô tả API. Để viết các đặc tả này, chúng ta có thể sử dụng hai định dạng file là JSON và YAML. JSON (JavaScript Object Notation) là một định dạng file phổ biến được sử dụng để lưu trữ và truyền tải dữ liệu. YAML (YAML Ain't Markup Language) là một định dạng file khác được sử dụng để lưu trữ và truyền tải dữ liệu. Cả hai định dạng file này đều có thể được sử dụng để viết các đặc tả Swagger 3. XML và CSV không phải là định dạng file được hỗ trợ bởi Swagger 3. HTML cũng không phải là định dạng file được hỗ trợ bởi Swagger 3. Vì vậy, đáp án đúng cho câu hỏi này là JSON hoặc YAML.

Để cung cấp một tóm tắt và mô tả cho một điểm cuối API cụ thể hoặc phương thức trong một controller, bạn cần sử dụng annotation @Operation. Annotation này được sử dụng để mô tả chi tiết về một phương thức hoặc điểm cuối API, bao gồm cả tên phương thức, mô tả phương thức, tham số đầu vào và đầu ra, v.v. Điều này giúp cho việc sử dụng và hiểu rõ về API trở nên dễ dàng hơn.

Để tích hợp Swagger 3 với ứng dụng Spring Boot 3, bạn cần thêm một số dependency vào file pom.xml hoặc build.gradle của dự án. Trong đó, dependency được sử dụng phổ biến nhất là springdoc-openapi-starter-webmvc-ui. Đây là một library được thiết kế để hỗ trợ việc tạo và quản lý API bằng cách sử dụng OpenAPI Specification. Nó cho phép bạn tạo và cấu hình API một cách dễ dàng, đồng thời cũng cung cấp các tính năng như tạo tài liệu API, tạo giao diện người dùng để tương tác với API, v.v. Ngoài ra, springdoc-openapi-starter-webmvc-ui cũng hỗ trợ các tính năng như tạo API theo tiêu chuẩn OpenAPI 3.0, tạo tài liệu API bằng cách sử dụng Markdown, v.v. Vì vậy, nếu bạn đang tìm kiếm một library để tích hợp Swagger 3 với ứng dụng Spring Boot 3, thì springdoc-openapi-starter-webmvc-ui là một lựa chọn tuyệt vời.