Cài đặt và sử dụng Swagger UI

Trong bài trước tôi đã giới thiệu với các bạn một số kiến thức cơ bản về Swagger. Trong bài này, tôi sẽ hướng dẫn các bạn cách cài đặt và sử dụng Swagger UI tool.

1. Tải thư viện Swagger UI

Các bạn download thư viện Swagger UI từ github repository tại link sau: https://github.com/swagger-api/swagger-ui.

Trong repository trên, bao gồm 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.

2. 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.

2.1. Tạo 1 file config để cấu hình API docs của project

Chúng ta sẽ sử dụng editor tool online 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 maixuanviet.com"
  version: "1.0.0"
  title: "Swagger UI Demo"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "contact@maixuanviet.com"
  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"

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.

4. 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ó kết quả 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ả.

5. Viết file swagger config hiệu quả với $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 vấn đề 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.

Để 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ử 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 các file config bây giờ đổ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: "contact@gpcoder.com"
  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 chúng ta đơn giản hơn rất nhiều. Chúng ta có thể dễ dàng thay đổi  hay thêm mới document cho API.

Trên đây là hướng dẫn cơ bản về cài đặt và sử dụng Swagger UI tool. Trong bài viết tiếp theo, chúng ta sẽ thực hiện tạo nội dung đặc tả cho api từ code có sẵn để hiện lên Swagger UI.