Swagger là gì? tạo document cho api restful web service

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

Chính vì thế, ta rất cần được có một quy định cung ứng câu hỏi chế tạo ra document APIs giúp dễ dàng mang đến bài toán cung cấp về cách thực hiện tài nguyên ổn trải qua APIs một cách kết quả. Hôm nay họ đã tìm hiểu về 1 cách thức tương đối danh tiếng dùng để làm viết document APIs: Swagger.

Bạn đang xem: Swagger là gì? tạo document cho api restful web service

Swagger là gì ?

Swagger là một trong open source dùng để làm cải cách và phát triển, thi công, tạo ra cùng làm cho tư liệu cho các khối hệ thống RESTfull Web Service. Ta gồm test của Swagger như sau:


*

*

Demo Swagger UI

Swagger cung ứng phần lớn qui định cung cấp câu hỏi tạo ra doc: Swagger UI, Swagger Editor, Swagger Codegen, Swagger Hub, Swagger Inspector. Trong số đó 3 hình thức thứ nhất là open source, Swagger Hub và swagger Inspector là đa số nguyên tắc cao cấp hơn tuy nhiên đã đề nghị trả mức giá, tuy nhiên bạn cũng có thể sử dụng không tính tiền trong khoảng 30 ngày. Vậy làm cho thuận lợi, chúng ta vẫn tìm hiểu các viết doc APIs bởi SwaggerUI cùng sơ lược về Swagger Hub.

Swagger UI là một trong những giải pháp góp gene 1 trang html css thể hiện về những APIs được thông số kỹ thuật vị 1 tệp tin .yaml. Ngoài ra, luật này còn được cho phép ta mockup mang lại api kia để xem hiệu quả (tất nhiên là api của công ty buộc phải chuyển động được đã :D).

Cài đặt Swagger UI

Bước 1: Tải tlỗi viện Swagger UI

Các bạn clone project Github này về, sau đó hãy copy thư mục dist vào project kia vào project của bạn và chọn render file index.html trong thư mục dist. Như vào project của tôi sử dụng Nodejs làm backend đã cấu hình như sau:


Khi kia, ví như ta chạy localhost:3000 trên trình phê chuẩn, ta sẽ được trang thử nghiệm Swagger UI trên.

Cách 2: Tạo config cấu hình các APIs của bạn

Cấu trúc cơ bạn dạng của một file .yaml trong Swagger như sau:

openapi: Phiên phiên bản Swagger sẽ áp dụng, sẽ định nghĩa toàn bộ cấu tạo tệp tin .yaml

info: Thông tin của APIs, trong này sẽ cất đầy đủ phần: title, version, description, ...

title: thương hiệu Open-APIs (thường xuyên là tên gọi thành phầm project mình làm)

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

description: Mô tả về APIs

security: Authentication mà lại APIs thực hiện để hỗ trợ tài nguyên

paths: Các APIs nhưng mà các bạn cung cấp mang lại đối tác

component: Định nghĩa những model sử dụng bởi vì APIs

Bên cạnh đó còn tương đối nhiều từ khóa không giống hoàn toàn có thể tham khảo sinh hoạt trang document của Swagger.

Swagger cũng cung cấp viết config theo định hình json, tuy vậy họ nên viết theo định hình yaml.

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

Sau kia, bọn họ save tệp tin cấu hìn bên dưới dạng đuôi .yaml vào thư mục dist tại bước 1, ở đây tôi đã lưu lại thành swagger.yaml.

Xem thêm: Tải Bản Ghost Win 8.1 - Tổng Hợp Bản Ghost Win 10, 8

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

Bây giờ hãy msinh hoạt tệp tin index.html vào thư mục dist, kiếm tìm với sửa path url của function SwaggerUIBundle thành băng thông chúng ta vừa tạo ra. Sau kia bảo quản, khởi chạy VPS, truy cập vào router đang trỏ tới tại bước 1 để trải nghiệm thành quả này nào :D.


*

*

Sửa lại đường dẫn cấu hình APIs

Để cho dễ hình dung, chúng ta hãy truy cập vào đây giúp thấy document RESTfull APIs nhưng tôi vừa tạo nên :D

Viết tệp tin .yaml thông số kỹ thuật đến hiệu quả...

Một loại khá xuất xắc của file .yaml là bạn cũng có thể tách riêng từng phần cùng call lại bọn chúng dựa vào cần sử dụng $ref. Chính vày điều đó, bạn có thể bóc những kết cấu tài liệu thành từng phần hiếm hoi rồi gọi bọn chúng lại. Điều này giúp tệp tin .yaml của bọn họ có một kết cấu dễ dàng chú ý dễ đọc cùng dễ nắm bắt.


*

Ngoài ra, file .yaml còn có thể chấp nhận được chúng ta bóc riêng biệt thành các tệp tin .yaml tương ứng, bọn họ hoàn toàn rất có thể tách từng đội APIs thuộc 1 trọng trách thành những tệp tin cá biệt, giúp tiết kiệm chi phí sức lực gọi cùng sửa cấu hình về sau rộng.

Về Swagger Hub, hình thức 3 vào 1

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

Để sử dụng hình thức dịch vụ này, tất nhiên là các bạn bắt buộc đăng ký 1 thông tin tài khoản không tính phí trial tại trang này. Phần này dễ dàng, các bạn từ làm được ✌️


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

Tiếp mang đến chúng ta sinh sản mới APIs trên Swagger Hub, nó vẫn dẫn ta mang lại 1 trang Editor cùng với định hình tệp tin .yaml. Tương từ nlỗi phương pháp viết .yaml họ đã áp dụng sinh sống Swagger UI.


Để coi Swagger UI họ lựa chọn Design View => Preview Docs.

Xem thêm: Free Download Đèn Ies Trong 3Dmax, Free Download 500 Đèn Ies Dành Cho Sketchup

Để Export ra code điện thoại tư vấn APIs, bọn họ chọn Export, chọn dạng cơ mà bọn họ ước ao xuất ra.

Tuy nhiên sử dụng Swagger Hub lại có một nhược điểm là ko tách bóc thành kết cấu file - thỏng mục, điều đó tạo file config siêu lâu năm cùng cực nhọc maintain. quý khách hãy thử tưởng tượng có một khối hệ thống 100 mẫu APIs cần public, mẫu mã tài liệu to lớn lớn chảng ... và tiếp nối câu hình lỗi 1 APIs thì vẫn sửa nỗ lực làm sao thất thoát
Chuyên mục: Công Nghệ