Blog

Tại sao ví dụ Swagger Petstore là một thiết kế REST API tồi?

Ashley Innocent

Ashley Innocent

13 tháng 3 2026

Tại sao ví dụ Swagger Petstore là một thiết kế REST API tồi?

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Tóm tắt

Swagger Petstore vi phạm các nguyên tắc REST cơ bản: nó sử dụng tên tài nguyên số ít không nhất quán, bao gồm động từ hành động trong URL, trả về mã trạng thái HTTP sai, hiển thị mật khẩu trong các yêu cầu GET và trả về các mảng trần mà không có siêu dữ liệu. Modern PetstoreAPI khắc phục tất cả các vấn đề này với thiết kế RESTful phù hợp, xử lý lỗi RFC 9457 và các mẫu sẵn sàng cho sản xuất.

Giới thiệu

Trong hơn một thập kỷ, Swagger Petstore đã là ví dụ mặc định để học OpenAPI. Hàng triệu nhà phát triển đã nghiên cứu nó, sao chép các mẫu của nó và xây dựng các API sản xuất dựa trên thiết kế của nó. Có một vấn đề: nó dạy bạn cách xây dựng các API tồi.

Swagger Petstore vi phạm các nguyên tắc REST cơ bản, bao gồm các lỗ hổng bảo mật và minh họa các anti-pattern gây hại cho hệ thống sản xuất. Nó giống như học lái xe với một chiếc xe có bàn đạp phanh và ga bị hoán đổi—bạn sẽ học được, nhưng bạn sẽ học sai.

Thiệt hại là có thật. Các nhà phát triển đã học từ Swagger Petstore mang những anti-pattern này vào mã sản xuất. Các API được xây dựng với cách đặt tên không nhất quán, phương thức HTTP sai và các lỗ hổng bảo mật. Các bài đánh giá mã bỏ qua những vấn đề này vì "Swagger làm thế đấy."

💡
Nếu bạn đang xây dựng hoặc kiểm thử API REST, Apidog giúp bạn xác thực thiết kế API dựa trên các nguyên tắc REST, kiểm thử hành vi điểm cuối và phát hiện các lỗi thiết kế trước khi chúng đến giai đoạn sản xuất. Bạn có thể nhập thông số kỹ thuật OpenAPI, chạy các bài kiểm thử tự động và đảm bảo API của mình tuân thủ các quy ước REST phù hợp.
button

Trong hướng dẫn này, bạn sẽ tìm hiểu chính xác những gì sai với Swagger Petstore, tại sao những vấn đề này lại quan trọng và cách Modern PetstoreAPI khắc phục chúng bằng các mẫu sẵn sàng cho sản xuất. Bạn sẽ thấy các so sánh song song, hiểu tác động của từng vi phạm và khám phá cách kiểm thử API của mình đúng cách với Apidog.

Vấn đề kế thừa của Swagger Petstore

Swagger Petstore được tạo ra vào năm 2011 như một ví dụ đơn giản cho đặc tả Swagger (nay là OpenAPI). Nó phục vụ mục đích của mình: trình bày cách viết một đặc tả OpenAPI. Nhưng nó chưa bao giờ được coi là một tài liệu tham khảo cho thiết kế API REST.

Tại sao nó trở thành tiêu chuẩn trên thực tế

Khi các nhà phát triển học OpenAPI, họ bắt đầu với ví dụ chính thức. Swagger Petstore chính là ví dụ đó. Nó có trong tài liệu, hướng dẫn và trình tạo mã. Nếu bạn đã sử dụng Swagger UI hoặc Swagger Codegen, bạn đã thấy nó.

Vấn đề: các nhà phát triển cho rằng "ví dụ chính thức = thực hành tốt nhất." Họ sao chép các mẫu mà không đặt câu hỏi. Các khóa học thiết kế API sử dụng nó làm công cụ giảng dạy. Các công ty xây dựng API nội bộ theo cấu trúc của nó.

Chi phí của những ví dụ tồi

Những ví dụ tồi tích tụ theo thời gian:

  1. Các nhà phát triển mới học anti-pattern - Họ không biết đây là những lỗi sai
  2. Trình tạo mã làm trầm trọng thêm các vấn đề - Các SDK được tạo ra kế thừa các lỗi
  3. Công cụ tài liệu hiển thị các ví dụ tồi - Swagger UI hiển thị Petstore theo mặc định
  4. Các công ty xây dựng API sản xuất theo cách này - "Nếu nó đủ tốt cho Swagger..."

Swagger Petstore có lẽ đã ảnh hưởng đến nhiều thiết kế API hơn bất kỳ ví dụ nào khác trong lịch sử. Đó là lý do tại sao những lỗi của nó lại quan trọng.

Các vi phạm REST nghiêm trọng trong Swagger Petstore

Hãy cùng xem xét các vi phạm REST cụ thể trong Swagger Petstore và lý do tại sao chúng sai.

1. Đặt tên tài nguyên không nhất quán (số nhiều so với số ít)

Vi phạm:

GET /pet/{petId}           ← Số ít
GET /store/inventory       ← Số nhiều
POST /pet                  ← Số ít
GET /user/{username}       ← Số ít

Tại sao sai:

Tài nguyên REST đại diện cho các bộ sưu tập. Một bộ sưu tập là số nhiều. Khi bạn truy cập /pets, bạn đang truy cập bộ sưu tập thú cưng. Khi bạn truy cập /pets/123, bạn đang truy cập mục 123 trong bộ sưu tập thú cưng.

Việc trộn số ít và số nhiều làm hỏng mô hình tư duy này. /pet/123 đang truy cập bộ sưu tập thú cưng hay một tài nguyên thú cưng duy nhất? Sự không nhất quán tạo ra sự nhầm lẫn.

Khắc phục bằng Modern PetstoreAPI:

GET /pets/{petId}          ← Luôn là số nhiều
GET /stores/inventory      ← Nhất quán
POST /pets                 ← Số nhiều cho bộ sưu tập
GET /users/{username}      ← Số nhiều ở mọi nơi

Modern PetstoreAPI sử dụng tên tài nguyên số nhiều một cách nhất quán trên tất cả các điểm cuối. Kiểm tra tài liệu API REST để biết cấu trúc điểm cuối hoàn chỉnh.

2. Động từ hành động trong URL

Vi phạm:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2
GET /user/login?username=john&password=secret
GET /user/logout

Tại sao sai:

URL REST nên đại diện cho tài nguyên (danh từ), không phải hành động (động từ). Phương thức HTTP là động từ. GET /pets có nghĩa là "lấy tài nguyên thú cưng". Việc thêm findByStatus là dư thừa—đó là chức năng của các tham số truy vấn.

Các động từ hành động trong URL cho thấy bạn đang nghĩ theo thuật ngữ RPC (Remote Procedure Call), chứ không phải thuật ngữ REST. Bạn đang tiết lộ chi tiết triển khai thay vì tài nguyên.

Khắc phục bằng Modern PetstoreAPI:

GET /pets?status=AVAILABLE              ← Tài nguyên + bộ lọc
GET /pets?tags=tag1,tag2                ← Tham số truy vấn để lọc
POST /auth/login                        ← Tài nguyên xác thực riêng biệt
POST /auth/logout                       ← Điểm cuối xác thực RESTful

Modern PetstoreAPI sử dụng các tham số truy vấn để lọc và các tài nguyên xác thực riêng biệt. Xem hướng dẫn xác thực để biết các mẫu xác thực phù hợp.

3. Mã trạng thái HTTP sai

Vi phạm:

POST /pet
Response: 200 OK          ← Nên là 201 Created

DELETE /pet/{petId}
Response: 200 OK          ← Nên là 204 No Content
{
  "message": "Pet deleted"
}

Tại sao sai:

Các mã trạng thái HTTP có ý nghĩa cụ thể:

Sử dụng 200 cho mọi thứ làm hỏng ngữ nghĩa HTTP. Các máy khách không thể phân biệt giữa "tài nguyên đã được truy xuất" và "tài nguyên đã được tạo". Trả về một nội dung với DELETE làm lãng phí băng thông—máy khách không cần văn bản xác nhận.

Khắc phục bằng Modern PetstoreAPI:

POST /pets
Response: 201 Created
Location: /pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "status": "AVAILABLE"
}

DELETE /pets/{petId}
Response: 204 No Content
(không có nội dung)

Modern PetstoreAPI sử dụng các mã trạng thái HTTP chính xác và bao gồm các tiêu đề Location cho các tài nguyên đã tạo. Kiểm tra hướng dẫn mã trạng thái HTTP để biết ánh xạ hoàn chỉnh.

4. Mảng trần không có siêu dữ liệu

Vi phạm:

GET /pet/findByStatus?status=available
Response: 200 OK
[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

Tại sao sai:

Trả về các mảng trần tạo ra vấn đề:

Khắc phục bằng Modern PetstoreAPI:

GET /pets?status=AVAILABLE
Response: 200 OK
{
  "data": [
    {"id": "019b4132-70aa-764f-b315-e2803d882a24", "name": "Fluffy"},
    {"id": "019b4127-54d5-76d9-b626-0d4c7bfce5b6", "name": "Buddy"}
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 45,
    "totalPages": 3
  },
  "links": {
    "self": "/pets?status=AVAILABLE&page=1",
    "next": "/pets?status=AVAILABLE&page=2",
    "last": "/pets?status=AVAILABLE&page=3"
  }
}

Modern PetstoreAPI bọc tất cả các bộ sưu tập trong các đối tượng có siêu dữ liệu và liên kết HATEOAS. Xem hướng dẫn phân trang để biết chi tiết triển khai.

5. Thiếu tiêu chuẩn lỗi

Vi phạm:

Response: 400 Bad Request
{
  "code": 400,
  "message": "Invalid input"
}

Tại sao sai:

Định dạng lỗi này không chuẩn và cung cấp thông tin tối thiểu:

Khắc phục bằng Modern PetstoreAPI:

Response: 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "errors": [
    {
      "field": "name",
      "message": "Name is required",
      "code": "REQUIRED_FIELD"
    },
    {
      "field": "status",
      "message": "Status must be one of: AVAILABLE, PENDING, SOLD",
      "code": "INVALID_ENUM"
    }
  ]
}

Modern PetstoreAPI sử dụng RFC 9457 Problem Details cho tất cả các lỗi. Xem hướng dẫn xử lý lỗi để biết định dạng lỗi hoàn chỉnh.

Các thảm họa bảo mật trong thiết kế cũ

Ngoài các vi phạm REST, Swagger Petstore còn có các vấn đề bảo mật nghiêm trọng.

Yêu cầu GET với mật khẩu

Vi phạm:

GET /user/login?username=john&password=secret123

Tại sao là thảm họa:

Mật khẩu trong các yêu cầu GET xuất hiện trong:

Đây là một lỗ hổng bảo mật nghiêm trọng. Mật khẩu không bao giờ nên nằm trong URL.

Khắc phục bằng Modern PetstoreAPI:

POST /auth/login
Content-Type: application/json
{
  "username": "john",
  "password": "secret123"
}

Response: 200 OK
{
  "accessToken": "eyJhbGc...",
  "refreshToken": "eyJhbGc...",
  "expiresIn": 3600
}

Modern PetstoreAPI sử dụng POST để xác thực với các nội dung JSON. Mật khẩu không bao giờ xuất hiện trong URL. Xem hướng dẫn xác thực để biết các mẫu OAuth 2.0 và JWT.

Khóa API trong tham số truy vấn

Vi phạm:

GET /pet/123?api_key=abc123secret

Tại sao sai:

Khóa API trong các tham số truy vấn có cùng vấn đề với mật khẩu trong URL:

Khắc phục bằng Modern PetstoreAPI:

GET /pets/019b4132-70aa-764f-b315-e2803d882a24
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Modern PetstoreAPI sử dụng các tiêu đề Authorization tiêu chuẩn cho khóa API và token. Xem hướng dẫn bảo mật để biết các mẫu xác thực.

Cách Modern PetstoreAPI khắc phục những vấn đề này

Modern PetstoreAPI được xây dựng từ đầu để trình bày thiết kế API REST phù hợp. Đây là những điểm khác biệt của nó:

Thiết kế REST sẵn sàng cho sản xuất

Các tiêu chuẩn hiện đại

Hỗ trợ đa giao thức

Không giống như Swagger Petstore (chỉ REST), Modern PetstoreAPI hỗ trợ:

Xem hướng dẫn giao thức để biết chi tiết triển khai.

Logic kinh doanh thực tế

Modern PetstoreAPI bao gồm các tính năng thực tế:

Kiểm tra tài liệu API để biết bộ tính năng hoàn chỉnh.

Kiểm thử thiết kế API REST với Apidog

Apidog giúp bạn xác thực thiết kế API REST và phát hiện các vi phạm trước khi chúng đến giai đoạn sản xuất.

Nhập và xác thực thông số kỹ thuật OpenAPI

# Nhập thông số kỹ thuật Modern PetstoreAPI
1. Mở Apidog
2. Nhấp vào "Import" → "OpenAPI"
3. Nhập: https://petstoreapi.com/openapi.json
4. Apidog xác thực thông số kỹ thuật và tạo các trường hợp kiểm thử

Apidog tự động phát hiện:

Kiểm thử các nguyên tắc REST

Tạo các trường hợp kiểm thử để xác minh sự tuân thủ REST:

Kiểm thử: Tên tài nguyên là số nhiều

// Kịch bản kiểm thử Apidog
pm.test("Endpoint sử dụng tên tài nguyên số nhiều", function() {
  const url = pm.request.url.toString();
  pm.expect(url).to.match(/\/pets\/|\/orders\/|\/users\//);
  pm.expect(url).to.not.match(/\/pet\/|\/order\/|\/user\//);
});

Kiểm thử: Mã trạng thái chính xác

pm.test("POST trả về 201 Created", function() {
  if (pm.request.method === "POST") {
    pm.response.to.have.status(201);
    pm.response.to.have.header("Location");
  }
});

pm.test("DELETE trả về 204 No Content", function() {
  if (pm.request.method === "DELETE") {
    pm.response.to.have.status(204);
    pm.expect(pm.response.text()).to.be.empty;
  }
});

Kiểm thử: Các bộ sưu tập có siêu dữ liệu

pm.test("Phản hồi bộ sưu tập bao gồm phân trang", function() {
  const response = pm.response.json();
  pm.expect(response).to.have.property("data");
  pm.expect(response).to.have.property("pagination");
  pm.expect(response.pagination).to.have.property("page");
  pm.expect(response.pagination).to.have.property("totalItems");
});

So sánh Petstore cũ và mới

Nhập cả hai đặc tả vào Apidog và chạy các so sánh song song:

  1. Nhập Swagger Petstore: https://petstore.swagger.io/v2/swagger.json
  2. Nhập Modern PetstoreAPI: https://petstoreapi.com/openapi.json
  3. Chạy các bài kiểm thử tự động trên cả hai
  4. So sánh kết quả để xem sự khác biệt

Apidog sẽ làm nổi bật các vi phạm thiết kế trong Swagger Petstore và cho thấy cách Modern PetstoreAPI khắc phục chúng.

Hướng dẫn di chuyển: Petstore cũ sang thiết kế hiện đại

Nếu bạn đã xây dựng một API dựa trên Swagger Petstore, đây là cách để di chuyển sang thiết kế REST phù hợp:

Bước 1: Sửa tên tài nguyên

Trước đây:

GET /pet/{petId}
POST /pet
DELETE /pet/{petId}

Sau đây:

GET /pets/{petId}
POST /pets
DELETE /pets/{petId}

Chiến lược di chuyển:

Bước 2: Loại bỏ động từ hành động

Trước đây:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2

Sau đây:

GET /pets?status=AVAILABLE
GET /pets?tags=tag1,tag2

Chiến lược di chuyển:

Bước 3: Sửa mã trạng thái HTTP

Trước đây:

POST /pet → 200 OK
DELETE /pet/{petId} → 200 OK with body

Sau đây:

POST /pets → 201 Created with Location header
DELETE /pets/{petId} → 204 No Content (không có nội dung)

Chiến lược di chuyển:

Bước 4: Bọc bộ sưu tập

Trước đây:

[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

Sau đây:

{
  "data": [...],
  "pagination": {...},
  "links": {...}
}

Chiến lược di chuyển:

Bước 5: Triển khai lỗi RFC 9457

Trước đây:

{
  "code": 400,
  "message": "Invalid input"
}

Sau đây:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [...]
}

Chiến lược di chuyển:

Tác động thực tế của thiết kế API tồi

Thiết kế API tồi có những chi phí thực tế:

Sự nhầm lẫn của nhà phát triển

Khi API vi phạm các nguyên tắc REST, nhà phát triển lãng phí thời gian:

Chi phí: Hàng giờ làm việc của nhà phát triển cho mỗi lần tích hợp

Lỗi máy khách

Các API không nhất quán dẫn đến lỗi phía máy khách:

Chi phí: Sự cố sản xuất và tác động đến khách hàng

Lỗ hổng bảo mật

Lỗi thiết kế tạo ra rủi ro bảo mật:

Chi phí: Vi phạm dữ liệu và vi phạm tuân thủ

Nợ kỹ thuật

Các ví dụ tồi tích tụ theo thời gian:

Chi phí: Gánh nặng bảo trì dài hạn

Kết luận

Swagger Petstore đã phục vụ mục đích của nó như một ví dụ OpenAPI đơn giản, nhưng đã đến lúc tiến lên. Các vi phạm REST, vấn đề bảo mật và anti-pattern của nó đã ảnh hưởng đến quá nhiều API sản xuất.

Modern PetstoreAPI cung cấp triển khai tham chiếu mà ngành công nghiệp cần: thiết kế REST phù hợp, tiêu chuẩn hiện đại, hỗ trợ đa giao thức và các mẫu sẵn sàng cho sản xuất. Hãy sử dụng nó làm tài liệu học tập và tham khảo cho thiết kế API của bạn.

Kiểm thử API của bạn bằng Apidog để phát hiện các vi phạm thiết kế sớm. Nhập thông số kỹ thuật OpenAPI của bạn, chạy các bài kiểm thử tự động và đảm bảo API của bạn tuân thủ các nguyên tắc REST trước khi chúng đến giai đoạn sản xuất.

Các bước tiếp theo:

  1. Khám phá tài liệu Modern PetstoreAPI
  2. So sánh thiết kế API của bạn với các mẫu Modern PetstoreAPI
  3. Nhập thông số kỹ thuật OpenAPI của bạn vào Apidog để xác thực
  4. Khắc phục các vi phạm REST bằng cách sử dụng hướng dẫn di chuyển ở trên
  5. Áp dụng RFC 9457 để xử lý lỗi

Thời đại của những ví dụ API tồi đã kết thúc. Xây dựng API đúng cách với Modern PetstoreAPI.

Câu hỏi thường gặp

Tại sao Swagger lại tạo ra một ví dụ tồi?

Swagger Petstore được tạo ra vào năm 2011 như một bản trình diễn đơn giản về đặc tả Swagger. Nó không được coi là tài liệu tham khảo thiết kế API REST. Vấn đề là nó đã trở thành ví dụ tiêu chuẩn trên thực tế, và những lỗi của nó đã được hàng triệu nhà phát triển sao chép.

Tôi có nên ngừng sử dụng Swagger Petstore không?

Có, đối với việc học thiết kế API REST. Thay vào đó, hãy sử dụng Modern PetstoreAPI. Nó trình bày các nguyên tắc REST phù hợp, tiêu chuẩn hiện đại và các mẫu sẵn sàng cho sản xuất. Petstore cũ dạy các anti-pattern gây hại cho hệ thống sản xuất.

Modern PetstoreAPI đã sẵn sàng cho sản xuất chưa?

Có. Modern PetstoreAPI bao gồm logic kinh doanh thực tế, xử lý lỗi phù hợp, xác thực, giới hạn tốc độ và các tính năng bảo mật. Bạn có thể triển khai nó với những sửa đổi tối thiểu hoặc sử dụng nó làm tài liệu tham khảo cho thiết kế API của riêng bạn.

Làm cách nào để kiểm tra xem API của tôi có tuân thủ các nguyên tắc REST không?

Nhập thông số kỹ thuật OpenAPI của bạn vào Apidog và chạy các bài kiểm thử tự động. Apidog xác thực việc đặt tên tài nguyên, mã trạng thái HTTP, cấu trúc phản hồi và các mẫu bảo mật. Bạn cũng có thể so sánh API của mình song song với Modern PetstoreAPI.

Lỗi lớn nhất trong Swagger Petstore là gì?

Sử dụng GET /user/login với mật khẩu trong tham số truy vấn. Điều này làm lộ mật khẩu trong lịch sử trình duyệt, nhật ký máy chủ và tiêu đề giới thiệu—một lỗ hổng bảo mật nghiêm trọng. Luôn sử dụng POST với nội dung JSON để xác thực.

Tôi có thể di chuyển từ các mẫu Swagger Petstore một cách dần dần không?

Có. Hỗ trợ cả điểm cuối cũ và mới trong giai đoạn chuyển đổi. Thêm cảnh báo lỗi thời vào các điểm cuối cũ, cập nhật tài liệu và theo dõi việc sử dụng. Xóa các điểm cuối cũ sau khi máy khách đã di chuyển (thường là 6-12 tháng).

Modern PetstoreAPI có hỗ trợ GraphQL và gRPC không?

Có. Không giống như Swagger Petstore (chỉ REST), Modern PetstoreAPI hỗ trợ nhiều giao thức: REST, GraphQL, gRPC, WebSocket, SSE, MQTT, Webhooks và MCP. Xem hướng dẫn giao thức để biết chi tiết.

Làm cách nào để thuyết phục nhóm của tôi sửa thiết kế API của chúng tôi?

Cho họ thấy những chi phí thực tế: sự nhầm lẫn của nhà phát triển, lỗi máy khách, lỗ hổng bảo mật và nợ kỹ thuật. Sử dụng Apidog để chứng minh các vi phạm trong API hiện tại của bạn. So sánh thiết kế của bạn với Modern PetstoreAPI và cho thấy những cải tiến.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống