OpenAPI là gì và một file mô tả API gồm những gì?

OpenAPI là chuẩn định dạng (YAML hoặc JSON), không phụ thuộc ngôn ngữ, để mô tả một HTTP API: endpoint, input, output và cơ chế bảo mật. Đây là hợp đồng máy đọc được giữa bên cung cấp và bên dùng API.

Một file gồm vài phần chính:

openapi: 3.1.0
info: { title: Orders API, version: 1.0.0 }
paths:
  /orders/{id}:
    get:
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: The order
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Order" }
components:
  schemas:
    Order:
      type: object
      properties: { id: { type: string }, total: { type: number } }

paths liệt kê các operation cùng parameter, request body và response. components chứa schema và security scheme dùng lại được. OpenAPI 3.1 dùng JSON Schema 2020-12 cho schema.

Từ một file, tool sinh ra tài liệu tương tác, client SDK, mock server và bộ validate request, còn linter kiểm tra style. Hãy coi nó là nguồn sự thật, đừng viết sau cùng.