What exactly do you specify in the OpenAPI specification?

The OpenAPI specification describes the REST API of a service, including:

• Endpoints (paths) with HTTP methods (GET, POST, PUT, DELETE, etc.)
• Request parameters (query, path, header, cookie)
• Request and response bodies with structure descriptions (data schemas)
• Response codes and their descriptions
• Data types and formats (e.g., string, integer, date-time)
• Security (authorization, authentication)
• Server information (URL, description)

Example:

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Thus, the OpenAPI specification serves as a formal contract between the client and the server, enabling the generation of documentation, client SDKs, and tests.