Vậy là bạn đã nghe nhiều về APIs—những cây cầu kỳ diệu giúp các ứng dụng giao tiếp với nhau—và bây giờ bạn muốn khám phá, tài liệu hóa chúng như một chuyên gia và kiểm tra mà không cần phải đổ mồ hôi. Giới thiệu Scalar, một viên ngọc mã nguồn mở khiến việc tài liệu hóa và kiểm tra API trở nên đơn giản như một cuộc dạo chơi trong công viên. Trong hướng dẫn dành cho người mới bắt đầu này, tôi sẽ nắm tay bạn để sử dụng Scalar tạo ra các tài liệu API tuyệt đẹp và thử nghiệm các điểm cuối, tất cả với một bầu không khí thoải mái và vui vẻ. Không cần phép thuật lập trình—chỉ cần sự tò mò và một chiếc laptop. Sẵn sàng để làm cho trò chơi API của bạn tỏa sáng? Hãy bắt đầu nào!
Scalar là gì? Người đồng hành API của bạn
Vậy, Scalar là gì? Đây là một nền tảng mã nguồn mở hiện đại được thiết kế để làm cho việc tài liệu hóa và kiểm tra API trở nên dễ dàng. Hãy nghĩ về nó như một cuốn sổ tay thời thượng biến các thông số API của bạn (như các tệp OpenAPI/Swagger) thành các tài liệu đẹp mắt, tương tác và là một sân chơi để kiểm tra các điểm cuối mà không cần công cụ bổ sung. Scalar cung cấp một client API REST, các tài liệu tham khảo ấn tượng và hỗ trợ OpenAPI hàng đầu, tất cả được đóng gói trong một giao diện không kêu gào “thiết kế vào năm 2011.” Nó mượt mà, thân thiện với lập trình viên và miễn phí để sử dụng.
Tại sao lại sử dụng Scalar? Nó cứu bạn khỏi những tài liệu nặng nề và nhàm chán, cho phép bạn kiểm tra các API ngay trong trình duyệt, và giữ cho đội của bạn hài lòng với các tài liệu tham khảo rõ ràng, có thể nhấp được. Dù bạn đang tài liệu hóa một API thanh toán hay kiểm tra một ứng dụng danh sách việc cần làm, Scalar sẽ hỗ trợ bạn. Hãy thiết lập thôi!
Cài đặt và thiết lập Scalar: Không rắc rối
Khởi động Scalar thật dễ như ăn bánh—không có công thức phức tạp nào ở đây. Các tài liệu tại guides.scalar.com rất rõ ràng, và tôi sẽ dẫn bạn qua cách khởi động thân thiện với người mới bắt đầu.
Bước 1: Chọn thiết lập của bạn
Scalar rất linh hoạt—bạn có thể sử dụng nó như một dịch vụ lưu trữ, nhúng nó vào một dự án, hoặc chạy nó cục bộ. Đối với người mới bắt đầu, hãy chọn cách đơn giản nhất: nhúng Scalar vào một tệp HTML cơ bản để chơi với một API. Bạn không cần phải cài đặt gì cả—chỉ cần một trình duyệt và một trình soạn thảo văn bản (như VS Code hoặc Notepad).
Bước 2: Tạo một tệp HTML Scalar
- Tạo một tệp: Mở trình soạn thảo văn bản của bạn và tạo một tệp mới có tên
scalar-api.html. - Thêm mã Scalar: Dán đoạn mã này từ tài liệu Scalar:
<!doctype html>
<html>
<head>
<title>Tài liệu tham khảo API Scalar của tôi</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<div id="app"></div>
<!-- Tải Scalar -->
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
<!-- Khởi tạo Scalar -->
<script>
Scalar.createApiReference('#app', {
url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json',
proxyUrl: 'https://proxy.scalar.com'
})
</script>
</body>
</html>
3. Lưu và mở: Lưu tệp, sau đó nhấp đúp vào nó để mở trong trình duyệt của bạn (Chrome, Firefox, v.v.). Tuyệt vời—bạn sẽ thấy giao diện sáng bóng của Scalar với một mẫu API (Scalar Galaxy) được tải.
Thiết lập này sử dụng CDN, vì vậy không cần máy chủ hoặc Node.js—hoàn hảo để bạn bắt đầu. Tôi đã thử nghiệm và mất chưa đến hai phút để thấy một tài liệu tham khảo API hoạt động. Bạn thấy thế nào?
Bước 3: Khám phá giao diện
Ngay sau khi được tải, Scalar sẽ hiển thị một thanh bên với các điểm cuối API, một bảng chính với tài liệu và một khu vực kiểm tra. Hãy nhấp xung quanh—nó rất tương tác! Mẫu Galaxy API là rất thú vị, nhưng chúng ta sẽ thay thế nó bằng thông số của bạn sớm thôi. Nếu bạn muốn phiên bản lưu trữ, hãy đăng ký tại scalar.com để có tài khoản miễn phí lưu giữ công việc của bạn.
Tạo tài liệu API với Scalar
Bây giờ, hãy sử dụng Scalar để tài liệu hóa một API. Giả sử bạn đang làm việc với một API danh sách việc cần làm—chúng ta sẽ làm cho nó trông chuyên nghiệp mà không cần viết một cuốn tiểu thuyết.
Bước 1: Lấy hoặc tạo một thông số OpenAPI
Scalar thích các tệp OpenAPI (hay còn gọi là Swagger)—JSON hoặc YAML mô tả các điểm cuối, tham số và phản hồi của API của bạn. Bạn có một cái không? Tuyệt vời! Nếu không, hãy tạo một cái đơn giản:
- Tạo một tệp có tên
todo-api.yaml:
openapi: 3.0.2
info:
title: API Danh sách việc cần làm
version: 1.0.0
description: Một API đơn giản để quản lý các nhiệm vụ
paths:
/tasks:
get:
summary: Liệt kê tất cả các nhiệm vụ
responses:
'200':
description: Một danh sách các nhiệm vụ
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
title:
type: string
post:
summary: Tạo một nhiệm vụ
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
responses:
'201':
description: Nhiệm vụ đã được tạo
2. Lưu nó trong thư mục dự án của bạn.
Đây là một thông số cơ bản, nhưng Scalar sẽ làm cho nó trông tuyệt vời.
Bước 2: Tải thông số vào Scalar
Để sử dụng thông số của bạn:
- Chạy nó (Tùy chọn): Hiện tại, hãy đặt
todo-api.yamlcùng thư mục vớiscalar-api.html. Nếu bạn có máy chủ web (nhưhttp.servercủa Python), hãy chạy:
python -m http.server 8000
Và bây giờ thông số của bạn nằm ở http://localhost:8000/todo-api.yaml.
- Cập nhật HTML: Thay đổi
urltrongscalar-api.htmlcủa bạn:
Scalar.createApiReference('#app', {
url: './todo-api.yaml', // hoặc http://localhost:8000/todo-api.yaml
proxyUrl: 'https://proxy.scalar.com'
})
- Tải lại: Mở lại
scalar-api.html. Voilà—Scalar hiển thị API danh sách việc cần làm của bạn với một thanh bên sạch sẽ, chi tiết các điểm cuối và phản hồi mẫu.
Các tài liệu hiện giờ đã tương tác—nhấp vào /tasks để xem chi tiết GET và POST. Scalar tự động tạo các mẫu mã trên Python, JavaScript và hơn thế nữa. Tôi đã ngạc nhiên khi thấy thông số YAML không hoàn hảo của mình trông thật đẹp!
Bước 3: Tùy chỉnh tài liệu của bạn
Muốn có phong cách? Chỉnh sửa cấu hình của Scalar:
Scalar.createApiReference('#app', {
url: './todo-api.yaml',
proxyUrl: 'https://proxy.scalar.com',
theme: 'purple', // Thử 'kepler' hoặc 'moon'
customCss: 'body { background-color: #f0f0f0; }'
})
Tải lại, và tài liệu của bạn sẽ nổi bật với một bầu không khí mới. Người dùng lưu trữ có thể lưu những điều này trên docs.scalar.com.
Kiểm tra APIs với Scalar
Đây là lúc Scalar trở nên cực kỳ thú vị—nó không chỉ dành cho tài liệu. Client API tích hợp sẵn cho phép bạn kiểm tra các điểm cuối ngay trong giao diện, không cần Postman.
Bước 1: Thiết lập một API có thể kiểm tra
Để kiểm tra, bạn cần một API đang hoạt động. Nếu bạn không có, hãy sử dụng một API thử nghiệm công khai như reqres.in. Cập nhật scalar-api.html của bạn:
Scalar.createApiReference('#app', {
url: 'https://reqres.in/api/openapi.yaml',
proxyUrl: 'https://proxy.scalar.com'
})
Tải lại, và Scalar sẽ tải cấu trúc API của ReqRes.
Bước 2: Kiểm tra các điểm cuối
- Trong Scalar, tìm một điểm cuối như
GET /api/users. - Nhấn nút “Thử nó” (trông giống như biểu tượng phát).
- Điền thông số (ví dụ,
page: 2) hoặc để mặc định. - Nhấn “Gửi đi.” Scalar sẽ gửi yêu cầu qua proxy của mình để tránh các vấn đề CORS và hiển thị phản hồi—mã trạng thái, tiêu đề và dữ liệu JSON.
Tôi đã thử nghiệm GET /api/users và nhận được một danh sách JSON rõ ràng về người dùng trong vài giây. Nếu bạn đang sử dụng API danh sách việc cần làm của mình, hãy lưu trữ nó cục bộ (ví dụ, với Node.js) và kiểm tra POST /tasks với một nội dung như {"title": "Học Scalar"}.
Bước 3: Gỡ lỗi và lặp lại
Thấy lỗi 404? Kiểm tra lại URL hoặc tiêu đề API trong bảng yêu cầu của Scalar. Client sẽ hợp tác hiển thị lỗi rõ ràng, vì vậy bạn có thể chỉnh sửa và thử lại nhanh chóng. Thêm mã thông báo xác thực hoặc tham số truy vấn trong giao diện—không cần mã lập trình.
Tại sao Scalar lại là giấc mơ của người mới bắt đầu
Scalar tỏa sáng cho những người mới vì:
- Cài đặt đơn giản: Một tệp HTML, và bạn đã sẵn sàng.
- Tài liệu tuyệt đẹp: Biến YAML lộn xộn thành cái đẹp có thể nhấp được.
- Kiểm tra tích hợp sẵn: Không cần công cụ bổ sung cho các kiểm tra nhanh.
- Cộng đồng sôi nổi: Các bài đăng trên X ca ngợi “sân chơi năng động” của nó dành cho các API.
So với Swagger UI, Scalar cảm thấy mới mẻ hơn và không cồng kềnh, với quy trình kiểm tra tốt hơn. Nó giống như người anh em thú vị làm mọi thứ trở nên vui vẻ.
Mẹo chuyên nghiệp để thành công với Scalar
- Bắt đầu nhỏ: Sử dụng một thông số đơn giản để tìm hiểu quy trình của Scalar.
- Tham gia Discord: Trò chuyện với những người yêu thích API tại discord.gg/scalar.
- Xác nhận các thông số: Dán YAML của bạn vào editor.swagger.io để phát hiện lỗi trước khi tải.
- Đi với phiên bản lưu trữ: Đăng ký tại scalar.com để hợp tác và tên miền con.
Kết luận: Cuộc phiêu lưu API của bạn với Scalar bắt đầu
Chúc mừng bạn—bây giờ bạn đã trở thành một siêu sao Scalar! Từ việc tạo các tài liệu API tương tác đến kiểm tra các điểm cuối như một chuyên gia, bạn đã mở khóa một công cụ làm cho các API trở nên ít đáng sợ hơn và thú vị hơn rất nhiều. Hãy thử tài liệu hóa một API cửa hàng thú cưng tiếp theo hoặc kiểm tra một cái công khai như JSONPlaceholder. Các tài liệu Scalar được packed với nhiều mẹo hơn, và cộng đồng đang sôi động trên Discord. Dự án API đầu tiên của bạn là gì? Một trò chơi? Một backend blog? À, và để làm cho API của bạn hoàn hảo hơn, hãy ghé qua apidog.com.
