APIs(Application Programming Interfaces) đang càng ngày trở nên phổ biến, những dịch vụ bên trên Internet phần nhiều đều sử dụng chuẩn RESTfull APIs để cung cấp cho những đối tác 1 phần tài nguyên của bản thân sử dụng. Vậy ta đặt ra câu hỏi là làm cho sao để cho các công ty đối tác biết bản thân được cung cấp những tài nguyên gì? Phải thực hiện những tin tức nào để rất có thể lấy được tài nguyên đó?

Chính bởi thế, ta yêu cầu phải có 1 công cụ hỗ trợ việc tạo nên document APIs giúp thuận tiện cho việc hỗ trợ về cách thực hiện tài nguyên trải qua APIs 1 cách hiệu quả. Bây giờ chúng ta sẽ tò mò về 1 phương pháp khá nổi tiếng dùng để viết document APIs: Swagger.Bạn vẫn xem: Swagger là gì? chế tạo ra document mang lại api restful web service

Swagger là gì ?

Swagger là 1 trong open source dùng để làm phát triển, thiết kế, kiến thiết và làm cho tài liệu cho các hệ thống RESTfull web Service. Ta bao gồm demo của Swagger như sau:


*

*

Demo Swagger UI

Swagger hỗ trợ những công cụ cung cấp việc tạo thành doc: Swagger UI, Swagger Editor, Swagger Codegen, Swagger Hub, Swagger Inspector. Trong những số đó 3 công cụ trước tiên là xuất hiện source, Swagger Hub và swagger Inspector là phần đa công cụ cao cấp hơn nhưng lại sẽ yêu cầu trả phí, mặc dù nhiên bạn có thể dùng không tính phí trong vòng 30 ngày. Vậy khiến cho thuận tiện, bọn họ sẽ khám phá các viết doc APIs bởi SwaggerUI cùng sơ lược về Swagger Hub.

Bạn đang xem: Swagger là gì

Swagger UI là 1 trong những công cụ giúp gene 1 trang html css miêu tả về các APIs được cấu hình bởi 1 tệp tin .yaml. Xung quanh ra, giải pháp này còn cho phép ta mockup mang đến api đó để xem hiệu quả (tất nhiên là api của người sử dụng phải vận động được vẫn :D).

Cài để Swagger UI

Bước 1: Tải tủ sách Swagger UI

Các bạn clone project Github này về, tiếp nối hãy copy folder dist trong project đó vào project của khách hàng và lựa chọn render tệp tin index.html trong folder dist. Như trong project của tôi sử dụng Nodejs có tác dụng backend đã cấu ngoài ra sau:

Khi đó, giả dụ ta chạy localhost:3000 bên trên trình duyệt, ta sẽ tiến hành trang demo Swagger UI mặt trên.

Bước 2: tạo thành config cấu hình các APIs của bạn

Cấu trúc cơ bản của 1 tệp tin .yaml vào Swagger như sau:

openapi: Phiên bản Swagger đã sử dụng, sẽ có mang toàn bộ kết cấu file .yaml

info: tin tức của APIs, vào này sẽ chứa hồ hết phần: title, version, description, ...

title: thương hiệu Open-APIs (thường là tên thành phầm project bản thân làm)

vertion: Phiên phiên bản APIs public

description: diễn đạt về APIs

security: Authentication nhưng mà APIs thực hiện để cung ứng tài nguyên

paths: những APIs cơ mà bạn cung ứng cho đối tác

component: Định nghĩa các mã sản phẩm sử dụng bởi APIs

Ngoài ra còn rất nhiều keyword khác rất có thể tham khảo ở trang document của Swagger.

Swagger cũng cung ứng viết config theo định hình json, tuy nhiên chúng ta nên viết theo định hình yaml.

Ta sẽ tạo nên file .yaml với cấu tạo như sau(được rước ngay vào file test của swagger) để thông số kỹ thuật các APIs:

Bước 3: cập nhật lại băng thông file config APIs và hưởng thụ thành quả

Bây tiếng hãy mở file index.html trong thư mục dist, tìm và sửa path url của function SwaggerUIBundle thành con đường dẫn họ vừa tạo. Tiếp đến lưu lại, khởi chạy server, truy cập vào router sẽ trỏ tới tại cách 1 để trải nghiệm thành quả làm sao :D.


*

*

*

Ngoài ra, file .yaml còn có thể chấp nhận được chúng ta bóc riêng thành những file .yaml tương ứng, bọn họ hoàn toàn gồm thể bóc từng team APIs cùng 1 trọng trách thành các file riêng biệt, góp tiết kiệm công sức đọc với sửa cấu hình sau này hơn.

Về Swagger Hub, thương mại & dịch vụ 3 vào 1

Swagger Hub là 1 dịch vụ hỗ trợ tính phí của Swagger phù hợp cho các công ty sử dụng và public APIs mang đến các công ty đối tác bằng câu hỏi generator APIs code, tuy nhiên họ vẫn được sử dụng không tính tiền trial trong 30 ngày. Swagger Hub có không thiếu thốn cả 3 công cụ xuất hiện source, cung ứng 1domain mang lại phép chúng ta public Swagger UI, cung ứng tool ren code tự file thông số kỹ thuật APIs và cung cấp cho bọn họ 1 cách thức để editor tệp tin .yaml cấu hình cho các APIs.

Để sử dụng thương mại & dịch vụ này, tất nhiên là chúng ta phải đk 1 tài khoản không tính tiền trial tại trang này. Phần này dễ, chúng ta tự làm được ✌️

Đăng ký kết 1 tài khoản Swagger Hub

Tiếp đến các bạn tạo mới APIs bên trên Swagger Hub, nó vẫn dẫn ta cho 1 trang Editor với định hình file .yaml. Tương tự như giải pháp viết .yaml họ đã sử dụng ở Swagger UI.

Để xem Swagger UI họ chọn Design View => Preview Docs.

Xem thêm: Cập Nhật Dispatcher Là Gì ? Mô Tả Công Việc Của Một Dispatcher

Để Export ra code call APIs, chúng ta chọn Export, lựa chọn dạng mà họ muốn xuất ra.

Tuy nhiên thực hiện Swagger Hub lại có 1 nhược điểm là không tách thành cấu tạo file - thư mục, điều này gây tệp tin config vô cùng dài và khó maintain. Các bạn hãy thử tưởng tượng có 1 hệ thống 100 chiếc APIs buộc phải public, kiểu tài liệu to bự chảng ... Và sau đó câu hình lỗi 1 APIs thì đã sửa nuốm nào nhỉ