APIs(Application Programming Interfaces) đang càng ngày càng trở đề xuất phổ biến, các dịch vụ trên Internet hầu như đều sử dụng chuẩn chỉnh RESTfull APIs để cung cấp cho những đối tác 1 phần tài nguyên của chính bản thân mình sử dụng. Vậy ta để ra thắc mắc là làm sao khiến cho các đối tác doanh nghiệp biết bản thân được hỗ trợ 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 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 UI

Bướ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 1

Swagger 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 Hub

Tiế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ỉ