Chính vị thế, ta đề xuất phải có 1 công cụ cung ứng việc tạo nên document APIs giúp thuận tiện cho việc cung cấp về cách sử dụng tài nguyên trải qua APIs một cách hiệu quả. Hôm nay chúng ta sẽ mày mò về 1 cơ chế khá nổi tiếng dùng để viết document APIs: Swagger.Bạn sẽ xem: Swagger là gì? chế tạo ra document mang đến api restful website service
Swagger là gì ?Swagger là một open source dùng để làm phát triển, thiết kế, phát hành và làm tài liệu đến các hệ thống RESTfull website Service. Ta gồm demo của Swagger như sau:


Demo Swagger UI
Swagger cung cấp những công cụ cung ứng việc tạo doc: Swagger UI, Swagger Editor, Swagger Codegen, Swagger Hub, Swagger Inspector. Trong các số đó 3 công cụ đầu tiên là mở cửa source, Swagger Hub cùng swagger Inspector là các công cụ cao cấp hơn dẫu vậy sẽ nên trả phí, mặc dù nhiên chúng ta cũng có thể dùng free trong vòng 30 ngày. Vậy để cho thuận tiện, chúng ta sẽ tìm hiểu các viết doc APIs bởi SwaggerUI cùng sơ lược về Swagger Hub.
Bạn đang xem: Swagger là gì? bạn hiểu gì về công cụ viết document cho api?
Swagger UI là 1 trong những công cố gắng giúp ren 1 trang html css biểu đạt về những APIs được thông số kỹ thuật bởi 1 file .yaml. Xung quanh ra, nguyên tắc này còn chất nhận được ta mockup mang đến api đó nhằm xem hiệu quả (tất nhiên là api của bạn phải vận động được đã :D).
Cài để Swagger UIBước 1: Tải tủ sách Swagger UI
Các chúng ta clone project Github này về, kế tiếp hãy copy thư mục dist trong project kia vào project của công ty và lựa chọn render tệp tin index.html trong thư mục dist. Như vào project của tôi sử dụng Nodejs làm backend đã cấu dường như sau:
Khi đó, giả dụ ta chạy localhost:3000 bên trên trình duyệt, ta sẽ được trang kiểm tra Swagger UI bên trên.
Bước 2: tạo config thông số kỹ thuật các APIs của bạn
Cấu trúc cơ phiên bản của 1 file .yaml vào Swagger như sau:
openapi: Phiên phiên bản Swagger đang sử dụng, sẽ định nghĩa toàn bộ cấu trúc file .yaml
info: tin tức của APIs, vào này đã chứa phần đa phần: title, version, description, ...
title: tên Open-APIs (thường là tên thành phầm project mình làm)
vertion: Phiên bạn dạng APIs public
description: biểu lộ về APIs
security: Authentication mà APIs thực hiện để cung ứng tài nguyên
paths: những APIs mà bạn hỗ trợ cho đối tác
component: Định nghĩa các model sử dụng vày APIs
Ngoài ra còn không ít keyword khác hoàn toàn có thể tham khảo sinh sống trang document của Swagger.
Swagger cũng hỗ trợ viết config theo định hình json, mặc dù nhiên chúng ta nên viết theo format yaml.
Ta sẽ khởi tạo file .yaml với kết cấu như sau(được rước ngay vào file thử nghiệm của swagger) để cấu hình các APIs:
Bước 3: update lại đường dẫn 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 cùng sửa path url của function SwaggerUIBundle thành đường dẫn bọn họ vừa tạo. Sau đó lưu lại, khởi chạy server, truy cập vào router vẫn trỏ tới tại bước 1 để hưởng thụ thành quả làm sao :D.



Ngoài ra, tệp tin .yaml còn cho phép chúng ta tách riêng thành nhiều file .yaml tương ứng, chúng ta hoàn toàn bao gồm thể bóc từng nhóm APIs thuộc 1 trách nhiệm thành những file riêng biệt, góp tiết kiệm công sức của con người đọ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 trong 1Swagger Hub là một trong dịch vụ cung ứng tính mức giá của Swagger thích hợp cho các công ty thực hiện và public APIs mang lại các công ty đối tác bằng câu hỏi generator APIs code, tuy nhiên chúng ta vẫn được sử dụng free trial vào 30 ngày. Swagger Hub có không hề thiếu cả 3 công cụ xuất hiện source, cung ứng 1domain mang lại phép bọn họ public Swagger UI, cung cấp tool gen code trường đoản cú file cấu hình APIs và hỗ trợ cho bọn họ 1 phương tiện để editor file .yaml cấu hình cho các APIs.
Để sử dụng dịch vụ thương mại này, tất nhiên là bạn phải đk 1 tài khoản không lấy phí trial trên trang này. Phần này dễ, chúng ta tự làm được ✌️
Đăng ký 1 thông tin tài khoản Swagger HubTiếp đến chúng ta tạo bắt đầu APIs trên Swagger Hub, nó vẫn dẫn ta đến 1 trang Editor với format file .yaml. Tựa như như giải pháp viết .yaml bọn họ đã áp dụng ở Swagger UI.
Để xem Swagger UI họ chọn Design View => Preview Docs.
Xem thêm: Giải Toán 11 Bài 2 Giới Hạn Của Hàm Số, Giải Toán 11 Bài 2: Giới Hạn Của Hàm Số
Để Export ra code hotline APIs, bọn họ chọn Export, chọn dạng mà chúng ta muốn xuất ra.
Tuy nhiên sử dụng 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, vấn đề này gây file config khôn xiết dài và khó maintain. Các bạn hãy thử tưởng tượng có một hệ thống 100 cái APIs phải public, kiểu dữ liệu to to chảng ... Và tiếp đến câu hình lỗi 1 APIs thì vẫn sửa thế nào nhỉ