Mục lục nội dung
Tải thư viện Swagger UI
Các bạn tải về thư viện Swagger UI từ github repository tại link sau : https://github.com/swagger-api/swagger-ui .Trong repository trên, gồm có 3 npm module khác nhau :
- swagger-ui : là một npm module có thể được sử dụng trong single-page application (SPA), nó tương thích với webpack để quản lý các dependency.
- swagger-ui-dist : module này bao gồm tất cả mọi thứ cần thiết để sử dụng Swagger UI ở phía server side hoặc SPA mà không cần cài đặt thêm các npm module dependencies.
- swagger-ui-react : cung cấp các React components được sử dụng cho các React application.
Sau khi download xong, bạn tìm đến thư mục swagger-ui/dist mở file index.html sẽ show lên một trang demo tương tự link http://petstore.swagger.io/ như sau:
Như bạn thấy, trong textbox Explore chính là đường linh tới nội dung đặc tả các api.
Deploy Swagger API lên server
Bạn có thể deploy Swagger lên bất kỳ server nào, đơn giản chỉ việc copy tất cả file trong thư mục dist lên server.
Tạo 1 file config để thông số kỹ thuật API docs của project
Chúng ta sẽ sử dụng editor tool trực tuyến của Swagger tại link sau https://editor.swagger.io/ để tạo file config cho document API .Sau đây mình sẽ tạo document cho API với cấu trúc như sau :
# swagger.yaml swagger: "2.0" info: description: "Swagger UI demo by gpcoder.com" version: "1.0.0" title: "Swagger UI Demo" termsOfService: "http://swagger.io/terms/" contact: email: "[email protected]" license: name: "Apache 2.0" url: "http://www.apache.org/licenses/LICENSE-2.0.html" schemes: - http basePath: "/api/v1" tags: - name: "Users" description: "Everything about user" paths: /users: post: tags: - "Users" summary: "Add new user" consumes: - "application/json" - "application/xml" produces: - "application/json" - "application/xml" parameters: - in: "body" name: "data" description: "New user info" schema: type: "object" properties: name: type: "string" example: "User 1" password: type: "string" example: "12345678" responses: 200: description: "Create user success" schema: type: "object" properties: name: type: "string" example: "User 1" 405: description: "Invalid input"
Các key trong file config mình đã diễn đạt rõ ở bài viết trước, những bạn hoàn toàn có thể xem lại tại link sau : https://blogchiase247.net/5967-gioi-thieu-swagger-cong-cu-document-cho-restfull-apis/
Lưu nội dung file trên với tên swagger.yaml tại thư mục swagger-ui/dist.
- Trên menu File của https://editor.swagger.io/ -> chọn Save as YAML hoặc chọn Convert and save as JSON.
Trỏ URL đến file config
Để sử dụng swagger, trong file dist/index.html cần phải trỏ URL đến file swagger đã tạo ở trên.
Tìm đến đoạn js cuối file, và đổi url: “http://petstore.swagger.io/v2/swagger.json” thành URL trỏ tới file swagger.yaml đã tạo ở trên.
Giả sử chúng ta đã deploy swagger lên server ở địa chỉ http://localhost:8012/swagger-ui/ và file swagger.yaml chúng ta đặt cùng thư mục với file index.html. Chúng ta sẽ sửa lại nội URL trên như sau:
http://localhost:8012/swagger-ui/swagger.yaml
Chúng ta có tác dụng như sau :
Swagger hỗ trợ cả YAML và JSON. Các bạn có thể thử đổi URL đến JSON để kiểm tra kết quả.
Viết file swagger config hiệu suất cao với USD ref
Chúng ta có thể tiếp tục thêm tất cả các API vào paths trong file swagger.yaml để hoàn thành document API cho project của mình.
Tuy nhiên có một yếu tố phát sinh là khi project càng phình to, càng nhiều API thì file swagger.yaml của lớn. Khi cần thêm mới hay chỉnh sửa sẽ rất khó khăn vất vả .
Để giải quyết vấn đề này chúng ta sẽ chia nhỏ file swagger.yaml ra thành nhiều file và sử dụng $ref trong swagger.yaml để trỏ tới những file mà ta vừa tách ra.
Giả sử tất cả chúng ta tái cấu trúc thư mục của mình như sau :
|__swagger-ui/
|__swagger.yaml
Bây giờ, mình sẽ tách file swagger.yaml ở trên ra theo cấu trúc thư mục như sau:
|__swagger-ui/
|__swagger.yaml
|__components/
|____users.yaml
Nội dung những file config giờ đây đổi lại như sau :
swagger.yaml
# swagger.yaml swagger: "2.0" info: description: "Swagger UI demo by gpcoder.com" version: "1.0.0" title: "Swagger UI Demo" termsOfService: "http://swagger.io/terms/" contact: email: "[email protected]" license: name: "Apache 2.0" url: "http://www.apache.org/licenses/LICENSE-2.0.html" schemes: - http basePath: "/api/v1" tags: - name: "Users" description: "Everything about user" paths: /users: $ref: components/users.yaml
components/users.yaml
# components/users.yaml post: tags: - "Users" summary: "Add new user" consumes: - "application/json" - "application/xml" produces: - "application/json" - "application/xml" parameters: - in: "body" name: "data" description: "New user info" schema: type: "object" properties: name: type: "string" example: "User 1" password: type: "string" example: "12345678" responses: 200: description: "Create user success" schema: type: "object" properties: name: type: "string" example: "User 1" 405: description: "Invalid input"
Như bạn thấy, nội dung file config của tất cả chúng ta đơn thuần hơn rất nhiều. Chúng ta hoàn toàn có thể thuận tiện đổi khác hay thêm mới document cho API .Trên đây là hướng dẫn cơ bản về thiết lập và sử dụng Swagger UI tool. Trong bài viết tiếp theo, tất cả chúng ta sẽ thực thi tạo nội dung đặc tả cho api từ code có sẵn để hiện lên Swagger UI .
Tài liệu tham khảo:
5.0
Nếu bạn thấy hay thì hãy chia sẻ bài viết cho mọi người nhé!
Shares
Bình luận
phản hồi
Source: https://blogchiase247.net
Category: Hỏi Đáp