Swagger basic

Swagger là gì?

• Mục tiêu của Swagger ™ là xác định một tiêu chuẩn, giao diện ngôn ngữ-agnostic để API REST cho phép cả người và máy tính để khám phá và tìm hiểu khả năng của các dịch vụ mà không cần truy cập vào mã nguồn, tài liệu, hoặc qua kiểm tra lưu lượng mạng.

• Khi định nghĩa đúng qua Swagger, một người tiêu dùng có thể hiểu và tương tác với các dịch vụ từ xa với một số lượng tối thiểu của logic thực hiện. Tương tự như những gì các giao diện đã làm cho lập trình cấp thấp hơn, Swagger loại bỏ các phỏng đoán trong cách gọi dịch vụ. Về mặt kỹ thuật - Swagger là một đặc điểm kỹ thuật chính thức được bao quanh bởi một hệ sinh thái lớn của các công cụ, trong đó bao gồm tất cả mọi thứ từ giao diện người dùng front-end, thư viện mã ở mức độ thấp và các giải pháp quản lý API thương mại.

Làm thế nào để bắt đầu?

• Nếu bạn là một nhà cung cấp API và muốn sử dụng để mô tả Swagger API của bạn - có rất nhiều cách tiếp cận có sẵn: Một cách tiếp cận từ trên xuống dưới, nơi bạn sẽ sử dụng Swagger Editor để tạo tài liệu Swagger của bạn và sau đó sử dụng các công cụ Swagger codegen tích hợp để tạo thực hiện máy chủ.

• Một cách tiếp cận từ dưới lên, nơi bạn có một API REST hiện có mà bạn muốn tạo một định nghĩa Swagger. Hoặc bạn tạo nét bằng tay (sử dụng cùng một Swagger biên tập đề cập ở trên), hoặc nếu bạn đang sử dụng một trong những khuôn khổ hỗ trợ (JAX-RS, Node.js, vv), bạn có thể lấy nét Swagger tạo tự động cho bạn. Nếu bạn đang làm JAX-RS có một cái nhìn vào ví dụ ở https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X.

• Nếu mặt khác bạn là một người tiêu dùng API ai muốn tích hợp với một API mà có một định nghĩa Swagger bạn có thể sử dụng phiên bản trực tuyến của giao diện người dùng Swagger để khám phá những API (cho rằng bạn có một URL để định nghĩa các API Swagger) - và sau đó sử dụng Swagger codegen để tạo ra các thư viện client của sự lựa chọn của bạn. Trong cả hai trường hợp - hãy chắc chắn kiểm tra danh sách dài của cả hai dự án mã nguồn mở và các nhà cung cấp thương mại mà có sẵn cho Swagger - có lẽ có cái gì đó có nhắm mục tiêu nhu cầu cụ thể của bạn.

Cấu trúc cơ bản

Swagger có thể được viết bằng JSON hoặc YAML. Trong hướng dẫn này, chúng tôi chỉ sử dụng các ví dụ YAML, nhưng nó cũng hoạt động tốt với kiểu JSON

Một ví dụ Swagger mẫu được viết bằng YAML giống như sau:

swagger: "2.0"
info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0

host: api.example.com
basePath: /v1
schemes:
  - https

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in Markdown.
      produces:
        - application/json
      responses:
        200:
          description: OK

Metadata

• Mỗi đặc điểm Swagger bắt đầu với phiên bản Swagger, phiên bản 2.0 là phiên bản mới nhất. Một phiên bản Swagger định nghĩa cấu trúc tổng thể của một đặc tả API - những gì bạn có thể tài liệu và cách bạn ghi lại nó.

swagger: "2.0"

Sau đó, bạn cần chỉ định thông tin API - tiêu đề, mô tả (tùy chọn), phiên bản (phiên bản API, không phải phiên bản tệp tin hoặc phiên bản Swagger).

 info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0

Phiên bản có thể là một chuỗi ngẫu nhiên.

Tham khảo : Info Object.

Base URL

URL cơ sở cho tất cả các cuộc gọi API được xác định bằng sơ đồ, máy chủ và cơ sở dữ liệu:

host: api.example.com
basePath: /v1
schemes:
  - https

Tất cả các đường dẫn API tương đối so với URL cơ sở. Ví dụ, /users tương đương với https://api.example.com/v1/users.

Tham khảo thêm về host và base UrL.

Consumes, Produces

Consumes and produces sections định nghĩa MIME types được hỗ trợ bởi API. Nó có thể overwrite ở các định nghĩa con

consumes:
  - application/json
  - application/xml
produces:
  - application/json
  - application/xml

Paths

The paths section xác định các điểm cuối (đường dẫn) riêng lẻ trong API của bạn và các phương pháp HTTP (các hoạt động) được hỗ trợ bởi các điểm cuối này. Ví dụ , GET /users có thể miêu tả như sau:

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in Markdown.
      produces:
        - application/json
      responses:
        200:
          description: OK

Thông tin thêm về path và các phép toán

Parameters

• Các hoạt động có thể có các tham số có thể được truyền qua đường dẫn URL (/ users / {userId}), chuỗi truy vấn (/ users? Role = admin), tiêu đề (X-CustomHeader: Value) và thân yêu cầu. Bạn có thể xác định các loại tham số, định dạng, chúng được yêu cầu hay không, và các chi tiết khác:

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
          minimum: 1
          description: Parameter description in Markdown.
      responses:
        200:
          description: OK

Responses

• Đối với mỗi thao tác, bạn có thể xác định các mã trạng thái có thể, chẳng hạn như 200 OK hoặc 404 Not Found, và lược đồ của cơ thể phản hồi. Schema có thể được định nghĩa nội tuyến hoặc tham chiếu từ một định nghĩa bên ngoài thông qua $$ref. Bạn cũng có thể cung cấp phản hồi ví dụ cho các loại nội dung khác nhau.

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
          minimum: 1
          description: The ID of the user to return.
      responses:
        200:
          description: A User object.
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 4
              name:
                type: string
                example: Arthur Dent
        400:
          description: The specified user ID is invalid (e.g. not a number).
        404:
          description: A user with the specified ID was not found.
        default:
          description: Unexpected error

Thêm thông tin về miêu tả response

Input and Output Models

• Phần định nghĩa cho phép bạn xác định cấu trúc dữ liệu phổ biến được sử dụng trong API của bạn. Chúng có thể được tham chiếu qua $$ref bất cứ khi nào một lược đồ được yêu cầu - cả cho cơ thể yêu cầu và cơ thể phản hồi. Ví dụ

{
  "id": 4,
  "name": "Arthur Dent"
}

có thể thể hiện như sau:

definitions:
  User:
    properties:
      id:
        type: integer
      name:
        type: string
    
    # Both properties are required
    required:  
      - id
      - name

và tham chiếu đến body như sau

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/User'
  /users:
    post:
      summary: Creates a new user.
      parameters:
        - in: body
          name: user
          schema:
            $ref: '#/definitions/User'
      responses:
        200:
          description: OK

Authentication

SecurityDefinitions và các từ khóa bảo mật được sử dụng để mô tả các phương pháp xác thực được sử dụng trong API của bạn.

securityDefinitions:
  BasicAuth:
    type: basic

security:
  - BasicAuth: []