Swagger UI là một công cụ tuyệt vời để trực quan hóa và tương tác với OpenAPI specs. Khi bạn làm việc với Swagger UI, bạn sẽ nhận thấy rằng các URL đóng vai trò quan trọng trong việc cấu hình và truy cập tài liệu API. Trong bài viết này, chúng ta sẽ giải thích rõ ràng các URL của Swagger UI để giúp bạn sử dụng chúng hiệu quả hơn.
Swagger UI là gì?
Swagger UI là một công cụ cho phép người dùng tương tác với các API bằng cách sử dụng tài liệu OpenAPI Specification. Nó đọc tài liệu đặc tả và hiển thị nó dưới định dạng tương tác trực quan. Điều này giúp các nhà phát triển hiểu các API, gửi yêu cầu kiểm tra, gỡ lỗi và sử dụng các REST API của bạn.
URL Swagger UI tương ứng với điểm cuối nơi bạn phục vụ tệp JSON đặc tả OpenAPI của bạn. Điều này có nghĩa là bạn cần cung cấp một địa chỉ web hướng tới vị trí của tệp JSON OpenAPI của bạn. Swagger UI đọc tệp này để tạo ra một giao diện thân thiện với người dùng có thể truy cập thông qua URL đó. Cấu trúc URL cụ thể có thể thay đổi do cấu hình máy chủ khác nhau.
Các tính năng của Swagger UI
Swagger UI là một công cụ mạnh mẽ cung cấp nhiều tính năng để kiểm tra, hiểu và trực quan hóa các API. Một số tính năng được đề cập bên dưới:
Các tính năng chính bao gồm:
- Kiểm tra API trực tiếp trong tài liệu
- Các điều khiển trực quan cho các tham số yêu cầu
- Phát sinh đoạn mã cho các cuộc gọi API
- Hỗ trợ Markdown cho định dạng
- Các công cụ cho sự hợp tác trong nhóm
- Trực quan hóa mô hình dữ liệu tự động
- Danh mục và tìm kiếm điểm cuối API
Các tham số URL của Swagger UI
Swagger UI có nhiều tham số trong URL để cấu hình hành vi và giao diện của nó. Những tham số này ảnh hưởng đến cách tài liệu API được hiển thị bằng cách sử dụng Swagger UI. Một số tham số URL Swagger UI thường được sử dụng nhất là:
URL:
Tham số này xác định URL của tệp đặc tả OpenAPI mà Swagger UI nên sử dụng để tạo tài liệu API. Định dạng của URL như sau:
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json
ConfigUrl:
configUrl cung cấp URL của một cấu hình JSON tùy chỉnh và thay đổi hành vi của Swagger UI.
http://localhost:8080/swagger-ui/?configUrl=/path/to/your/config.json
deepLinking:
Tham số này cho phép liên kết sâu đến các hoạt động hoặc thẻ cá nhân trong tài liệu API. Nó hữu ích khi chia sẻ liên kết trực tiếp đến các phần cụ thể của tài liệu.
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&deepLinking=true
oauth2RedirectUrl:
Tham số này cho phép người dùng chuyển hướng đến một URL khác sau khi xác thực thành công khi API của bạn yêu cầu xác thực OAuth 2.0.
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&oauth2RedirectUrl=https://your-app.example.com/oauth2-redirect
defaultModelsExpandDepth:
Tham số này điều chỉnh độ sâu mặc định của các mô hình trong tài liệu.
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&defaultModelsExpandDepth=2
Cách tìm URL Swagger UI
Nhiều người bối rối về việc đâu là URL Swagger UI. Nó được tạo ra dựa trên cấu hình của dự án của bạn. Để tìm URL, hãy làm theo các bước sau:
- Đảm bảo rằng dự án của bạn được cấu hình để tạo tài liệu Swagger.
- Để truy cập Swagger UI, bạn cần kết hợp URL cơ bản của API với điểm cuối tài liệu Swagger. Điều này sẽ tạo ra URL Swagger UI của bạn.
Ví dụ, nếu bạn đang lưu trữ API của mình tại http://localhost:3000 và điểm cuối swagger của bạn là /swagger-ui/, thì URL Swagger của bạn sẽ trở thành http://localhost:8080/swagger-ui/.
Nếu bạn vẫn gặp khó khăn trong việc tìm URL Swagger UI của mình, bạn có thể tham khảo tài liệu của khung hoặc thư viện mà bạn đang sử dụng để tạo các API của bạn. Điều này sẽ giúp cung cấp thông tin về cách truy cập URL cho cấu hình cụ thể của bạn.
Cách thay đổi đường dẫn Defauth của Swagger UI?
Đường dẫn mặc định của Swagger UI phụ thuộc vào cấu hình của máy chủ của bạn. Nó được xây dựng dựa trên vị trí và nơi bạn đã triển khai Swagger UI. Các đường dẫn URL mặc định có thể được thay đổi theo yêu cầu của người dùng và quá trình triển khai. Tham số URL trong URL nên chỉ tới vị trí của tệp đặc tả OpenAPI.
Có nhiều phương pháp để thay đổi đường dẫn mặc định của URL Swagger UI.
Thay đổi tệp cấu hình Swagger (Apache và Nginx):
Nếu bạn đang sử dụng máy chủ web, bạn có thể thay đổi cấu hình của máy chủ của bạn để xử lý các yêu cầu tại một URL cụ thể.
Apache:
Trong trường hợp của Apache, bạn có thể sửa đổi tệp cấu hình của mình để tạo ra một quy tắc rewrite để các yêu cầu có thể được chuyển hướng đến đường dẫn Swagger UI của bạn. Bạn phải mở tệp cấu hình của mình, thường được đặt tên là ‘httpd.conf’ hoặc ‘apache2.conf’. Thêm quy tắc rewrite của bạn cho đường dẫn mong muốn trong tệp này.
RewriteEngine On
RewriteRule ^/api-docs/(.*)$ /path/to/your/swagger-ui/$1 [L]
Bạn có thể khởi động lại máy chủ Apache của mình để các thay đổi được phản ánh.
Nginx:
Nếu bạn đang sử dụng Nginx, bạn phải cập nhật cấu hình tệp máy chủ của bạn để định nghĩa một vị trí cho việc xử lý các yêu cầu của bạn. Trong khối máy chủ, thêm vị trí của bạn.
server {
listen 80;
server_name your-domain.com;
location /api-docs {
alias /path/to/your/swagger-ui;
index index.html;
}
}
Kiểm tra xem có bất kỳ lỗi cú pháp nào sau khi thực hiện các thay đổi và tải lại Nginx để các thay đổi được phản ánh.
Sử dụng các khung như Express.js:
Sử dụng Express.js, bạn có thể cấu hình các tuyến đường của mình để xử lý các yêu cầu Swagger UI.
Để phục vụ Swagger UI, bạn phải xác định một tuyến đường trong tệp máy chủ Express.js của bạn.
const express = require('express');
const app = express();
app.use('/custom-path', express.static('swagger-ui'));
app.listen(3000, () => {
console.log('Máy chủ đang chạy trên cổng 3000');
});
Điều này sẽ cho phép bạn truy cập Swagger UI của bạn trên ‘custom-path’ của bạn.
Tận dụng Springboot để thay đổi đường dẫn mặc định:
Trong một ứng dụng Spring Boot, bạn có thể sửa đổi các tệp ‘application.properties’ hoặc ‘application.yml’. Bạn có thể thêm thuộc tính sau để thay đổi đường dẫn Swagger UI mặc định trong các tệp ‘application.properties’ hoặc ‘application.yml’ của bạn.
springfox.documentation.swagger-ui.path=/custom-path
Bạn có thể thay thế ‘/custom-path’ theo đường dẫn mong muốn của bạn.
Tiếp theo, bạn cần cấu hình bean để tùy chỉnh đường dẫn. Bạn có thể mở rộng ‘WebMvcConfigurerAdapter’ để đạt được điều này.
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class SwaggerUIConfiguration implements WebMvcConfigurer {
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addRedirectViewController("/custom-path", "/swagger-ui.html");
}
}
Đảm bảo rằng bạn có các phụ thuộc cần thiết trong Swagger để đạt được những kết quả này.
Bạn sau đó cần cấu hình lớp chính của ứng dụng của bạn.
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("your.package.name"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Tài liệu API của bạn")
.version("1.0")
.build();
}
}
Thay thế “your.package.name” bằng gói cơ sở của các bộ điều khiển của bạn.
Khởi tạo Swagger UI:
Bạn có thể điều chỉnh tham số ‘url’ để phản ánh đường dẫn URL mong muốn của bạn. Điều này sẽ cho phép bạn thay đổi đường dẫn mặc định của Swagger UI. Khi khởi tạo Swagger UI trong JavaScript, bạn có thể thực hiện những thay đổi sau.
const ui = SwaggerUIBundle({
url: "/custom-path/swagger.json",
});
Sử dụng Swagger UI để kiểm tra API
Giống như các công cụ kiểm tra API khác, chẳng hạn như Apidog, Swagger UI cung cấp một cách hiệu quả và thân thiện với người dùng để kiểm tra các API. Bạn phải làm theo một số bước nhất định để gỡ lỗi và kiểm tra các API của bạn bằng cách sử dụng trang Swagger . Nhấp vào Live Demo và bắt đầu khám phá Swagger UI. Bạn sẽ thấy một cửa sổ như vậy mở ra.
Bạn có thể khám phá nhiều phương thức HTTP/HTTPS như POST, GET, PUT, v.v.
Bạn có thể nhấp vào bất kỳ phương thức nào và khám phá xung quanh. Nếu bạn nhấp vào phương thức POST, bạn sẽ thấy một tùy chọn để tải lên một hình ảnh và cập nhật các tham số của phương thức. Bạn có thể nhấn ‘Execute’, và yêu cầu của bạn sẽ được thực thi.
Bạn có thể thấy phản hồi cho yêu cầu POST bằng cách cuộn xuống.
Tương tự, bạn có thể làm việc với các phương thức khác và xem chúng hoạt động như thế nào. Điều này sẽ giúp bạn có một ý tưởng tốt về cách hoạt động của Swagger UI.
Hãy xem xét Apidog để có tài liệu API mạnh mẽ hơn ngoài khả năng của Swagger UI. Apidog cho phép quản lý toàn bộ vòng đời API bao gồm thiết kế, mô phỏng, kiểm tra, phiên bản, hợp tác và nhiều hơn nữa.
Với các tính năng nâng cao như tích hợp CI/CD và quy trình làm việc của nhóm, Apidog cung cấp một bộ công cụ hoàn chỉnh hơn để tối ưu hóa quá trình cung cấp API. Nền tảng toàn diện của nó mở rộng phát triển API và cải thiện năng suất.
Khắc phục sự cố Swagger UI Localhost
Nếu bạn gặp vấn đề với URL Swagger UI trên localhost, có một số bước khắc phục sự cố mà bạn có thể xem xét để chẩn đoán và giải quyết vấn đề.
- Đảm bảo rằng máy chủ API của bạn đang hoạt động. Swagger UI không thể truy xuất tài liệu nếu máy chủ của bạn gặp vấn đề trong việc chạy.
- Kiểm tra cấu hình Swagger của bạn xem có được thiết lập đúng không.
- Sử dụng URL Swagger UI chính xác với các điểm cuối đúng.
- Xóa bộ nhớ cache của trình duyệt. Đôi khi, các lỗi không mong muốn có thể xảy ra với dữ liệu được lưu trong cache.
- Khởi động lại cả máy chủ API và trình duyệt của bạn sau khi thực hiện bất kỳ thay đổi nào.
- Kiểm tra kỹ định dạng URL mà bạn đang sử dụng để truy cập Swagger UI.
Kết luận
Tóm lại, Swagger UI đang nhanh chóng trở nên phổ biến trong số các nhà phát triển nhờ các kỹ thuật quản lý API đa dạng của nó. Nó cung cấp tài liệu được cấu trúc tốt và giao diện thân thiện với người dùng. Người dùng cũng có thể trực quan hóa các mô hình dữ liệu trong khi thực hiện kiểm tra API trực tiếp, khiến nó trở thành một lựa chọn tốt cho việc kiểm tra và gỡ lỗi API.
Mặc dù Swagger UI có những lợi thế của nó, nhưng cũng có một số hạn chế mà người dùng có thể thấy trong quá trình kiểm tra API. Nó cung cấp sự hợp tác hạn chế giữa các nhà phát triển và không hỗ trợ tích hợp với các công cụ quản lý API khác.