What is OpenAPI and what does an API description file contain?

OpenAPI is a standard, language-neutral format (YAML or JSON) for describing an HTTP API: its endpoints, inputs, outputs and security. It is the machine-readable contract between provider and consumers.

A file has a few top-level parts:

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 lists operations with parameters, request bodies and responses. components holds reusable schemas and security schemes. OpenAPI 3.1 uses JSON Schema 2020-12 for schemas.

From one file, tools generate interactive docs, client SDKs, mock servers and request validators, and linters check style. Treat it as the source of truth, not an afterthought.