Điều khoản Swagger và OpenAPI

Trong khi tôi đang viết bài báo trước, bài báo chưa bao giờ được xuất bản này, tôi nhận ra rằng nhiều người không hiểu sự khác biệt giữa thuật ngữ Swagger và OpenAPI (OAS) . Mọi người sử dụng cả hai thuật ngữ thay thế cho nhau. Tôi không trách họ vì tôi cũng có những nghi ngờ tương tự.

Swagger cho phép bạn mô tả cấu trúc API của mình để máy có thể đọc chúng.
— vênh váo

Nếu bạn cố gắng tìm kiếm Swagger hoặc OpenAPI trên google , trong hầu hết các trường hợp, bạn sẽ đến SwaggerIO , trang web chính thức của Swagger. Nếu bạn hỏi tôi, trang web đã che khuất mục đích của Swagger kể từ ngày đầu tiên. Không cố ý, mặc dù. Thông tin không thiếu, nó chỉ không được trình bày một cách rõ ràng và ngắn gọn.

Đặc tả OpenAPI (OAS) xác định giao diện bất khả tri ngôn ngữ tiêu chuẩn cho API RESTful, cho phép cả con người và máy tính khám phá và hiểu các khả năng của dịch vụ mà không cần truy cập vào mã nguồn, tài liệu hoặc thông qua kiểm tra lưu lượng mạng.
— vênh váo

Ngày nay, có nhiều bài viết về chủ đề này, do đó việc tìm ra sự khác biệt dễ dàng hơn nhiều, nhưng vẫn có thể tìm thấy các bài viết xen lẫn các thuật ngữ. SwaggerIO đang quảng bá Swagger dưới dạng một bộ công cụ và OpenAPI dưới dạng thông số kỹ thuật. Có thể nói rằng Swagger được sử dụng để tạo đặc tả OpenAPI . Về cơ bản, tuyên bố này không sai, nhưng nó không phải là toàn bộ sự thật.

Cách sử dụng các điều khoản

Thông thường, các nhà phát triển sử dụng thuật ngữ Swagger trong ít nhất hai ngữ cảnh:

• để mô tả một bộ công cụ để thực hiện đặc tả. Một số công cụ là Swagger Editor, Swagger UI, Swagger Codegen, v.v. Đó là một hệ sinh thái.
• để mô tả thông số kỹ thuật của phiên bản 2.*.*

Các nhà phát triển chủ yếu sử dụng thuật ngữ Đặc tả OpenAPI 3 trong một ngữ cảnh duy nhất:

• để mô tả thông số kỹ thuật của phiên bản 3.*.*. Cộng đồng gọi là OAS, OAS3, OpenAPI Spec, OpenAPI 3 Specification, v.v. Họ đã sử dụng OpenAPI 3 làm phiên bản kế thừa của Swagger Specification 2.

Swagger và OpenAPI là bạn thân của nhau là có lý do. Lịch sử là thành phần quan trọng ở đây.

Công ty SmartBear duy trì Swagger. Vào tháng 11 năm 2015, Tổ chức Linux đã thông báo rằng họ đang tạo ra, cùng với SmartBear, Google, Microsoft, Paypal và một số công ty khác, một tổ chức mới, Sáng kiến ​​OpenAPI. Nhiệm vụ chính của sáng kiến ​​là mở rộng đặc điểm kỹ thuật của Swagger.

Vài tháng sau, sáng kiến ​​đổi tên Swagger thành đặc tả OpenAPI. Sáng kiến ​​đã nhân bản mã vào kho lưu trữ mới. Từ thời điểm đó, các cá nhân đã sử dụng cả hai thuật ngữ trong các ngữ cảnh khác nhau.

Từ cuối cùng

Swagger từng là một bộ công cụ, thông số kỹ thuật và tất cả trong một. Ngày nay, Swagger là một bộ công cụ. OpenAPI là một đặc điểm kỹ thuật. Đó là nó.

Thật tuyệt khi biết sự khác biệt. Tuy nhiên, cho dù bạn sử dụng thuật ngữ nào, phía bên kia sẽ hiểu bạn - cuối cùng, đó là điều duy nhất quan trọng.