Trong các bài viết trước thì chúng tôi đã giới thiệu các bạn cách sử dụng API Blueprint để viết tài liệu cho Restful web API, nhưng hôm nay sau khi chúng tôi thử một công cụ mới có tên là Swager thì thấy khá là tuyệt vời do đó trong bài viết này chúng tôi sẽ hướng dẫn các bạn các khái niệm cơ bản.
Swagger là gì?
Swagger là một tool cho phép bất kỳ ai – từ developers cho đến end users – có thể hình dung và tương tác với các tài nguyên API của dự án. Tool này sẽ tự động generates ra API documents từ file config Swagger, với cái nhìn trực quan và việc triển khai trở nên dễ dàng hơn cho phía client. Nó gồm 3 thành phần mỗi thành phần có một công dụng riêng, ví dụ như bạn muốn tự động tạo api thì bạn dùng Swagger editor sau đó bạn chọn ngôn ngữ bạn muốn nó tạo, xem thêm http://editor.swagger.io/
Cách dùng
Bạn có thể tải nó về chạy dưới máy local, nhưng cá nhân tôi thì thích dùng online hơn, do đó bạn truy cập vào trang https://swagger.io/ sau đó bạn dăng ký một tài khoản, hiện tại nó cung cấp cho bạn 2 phiên bản có phí và miễn phí, bạn cứ chọn miễn phí khá là nhiều tính năng bạn dùng không hết đâu, sau khi bạn đăng nhập vào nó có giao diện như thế này.
Mặc định nó cung cấp khá là nhiều mẫu template, ví dụ nếu bạn muốn thiết kế API cho dự án IOT thì chọn mẫu đó, cá nhân tôi thì đang thiết kế API cho thú cưng nên chọn mẫu là petstore.
thì nó tạo cho mình một file swagger.yaml với cấu trúc mẫu như sau:
```
swagger: '2.0'
info:
description: |
Provide a way for your application to access data on Lackky's platform. Through the HTTP protocol the application can query user data, friend data, new messages and many other tasks.
version: "1.0.0"
title: Swagger Petstore
termsOfService: http://swagger.io/terms/
contact:
email: [email protected]
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
# host: petstore.swagger.io
# basePath: /v2
tags:
- name: pet
description: Everything about your Pets
externalDocs:
description: Find out more
url: http://swagger.io
- name: store
description: Access to Petstore orders
- name: user
description: Operations about user
externalDocs:
description: Find out more about our store
url: http://swagger.io
# schemes:
# - http
paths:
/pet:
post:
tags:
- pet
summary: Add a new pet to the store
operationId: addPet
consumes:
- application/json
- application/xml
produces:
- application/json
- application/xml
parameters:
- in: body
name: body
description: Pet object that needs to be added to the store
required: true
schema:
$ref: '#/definitions/Pet'
responses:
405:
description: Invalid input
security:
- petstore_auth:
- write:pets
- read:pets
```Một số keys trong file config trên
- info: Thông tin cấu hình
- basePath: đường dẫn gốc đến thư mục API của project, trong ví dụ này là /v2
- tags: Định nghĩa những cái tags, có thể sử dụng để gom những API trong cùng một controllers về một nhóm
- paths: đường dẫn đến API, trong ví dụ này /pet tức là URL của API này sẽ là /pet vì bạn đã comment khai báo basePath ở trên nên có thể lược bỏ phần base, nếu bạn bỏ comment basepath thì API lúc này là /v2/pet
Tuy nhiên có một vấn đề đó là khi project càng phình to, càng nhiều API thì chẳng phải file swagger.yaml của bạn sẽ dài đến vô tận sao, và lúc đó việc click vào file này để sửa API hoặc thêm mới sẽ trở nên khó khăn rất nhiều, Swagger có cung cấp cho ta một tính năng đó là $ref bạn có thể tham khảo tại link này https://swagger.io/docs/specification/using-ref/
Swagger sử dụng định dạng yaml khá là thuận tiện cho chúng ta đọc và hiểu, nếu bạn nào chưa biết về nó có thể xem bài viết yaml là gì
Hình dưới này là kết quả sau khi chúng tôi tạo dự án cho pet camera sắp tới.
Kết luận
Tài liệu hướng dẫn là yếu tố quan trọng để có một trải nghiệm tốt khi sử dụng API. Nó không chỉ làm hài lòng khách hàng mà còn giúp số lượng người sử dụng API của bạn tăng lên. Trong bài viết này chúng tôi đã giới thiệu các bạn căn bản dịch vụ Swagger, chi tiết cách dùng tôi nghĩ bạn hãy dùng rồi chia sẽ với chúng tôi ^^
Bạn có thể xem bản demo của chúng tôi tạo ở trên https://app.swaggerhub.com/apis-docs/duythien/lackky/1.0.0#/user/createUser
