openapi: 3.0.3
info:
  title: Notes API
  version: 1.0.0
  description: |
    Compact example OpenAPI spec for a small REST API.
    Intended as a sample deliverable for documentation bids.
servers:
  - url: https://api.example.com
paths:
  /notes:
    get:
      summary: List notes
      operationId: listNotes
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        "200":
          description: Notes returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Note"
  /notes/{noteId}:
    get:
      summary: Get note by ID
      operationId: getNote
      parameters:
        - $ref: "#/components/parameters/NoteId"
      responses:
        "200":
          description: Note found
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Note"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      summary: Update note title
      operationId: updateNote
      parameters:
        - $ref: "#/components/parameters/NoteId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateNoteRequest"
            example:
              title: Ship the docs
      responses:
        "200":
          description: Note updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Note"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"
components:
  parameters:
    NoteId:
      in: path
      name: noteId
      required: true
      schema:
        type: string
        format: uuid
      description: Note identifier
  responses:
    BadRequest:
      description: Invalid request payload
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error:
              code: VALIDATION_ERROR
              message: title is required
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error:
              code: NOT_FOUND
              message: note not found
  schemas:
    Note:
      type: object
      required:
        - id
        - title
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        body:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
    UpdateNoteRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string