openapi: 3.1.0
info:
  title: grapeminds Wine API
  version: 1.0.0
  summary: Public wine data API for wines, producers, regions and pairings.
  description: |
    Machine-readable OpenAPI description for the grapeminds public API.
    Base URL: https://api.grapeminds.eu/public/v1
servers:
  - url: https://api.grapeminds.eu/public/v1
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /wines:
    get:
      summary: List wines
      operationId: listWines
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
        - in: query
          name: per_page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 15
        - in: query
          name: color
          schema:
            type: string
            enum: [red, white, rose]
        - in: query
          name: producer_id
          schema:
            type: integer
        - in: query
          name: region_id
          schema:
            type: integer
      responses:
        '200':
          description: Wine list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WineListResponse'
  /wines/search:
    get:
      summary: Search wines
      operationId: searchWines
      parameters:
        - in: query
          name: q
          required: true
          schema:
            type: string
            minLength: 3
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Search response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WineSearchResult'
                  meta:
                    type: object
                    properties:
                      query:
                        type: string
                      count:
                        type: integer
  /wines/{id}:
    get:
      summary: Get wine details
      operationId: getWine
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Wine details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WineDetails'
        '404':
          description: Wine not found
  /producers:
    get:
      summary: List producers
      operationId: listProducers
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
        - in: query
          name: per_page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 15
        - in: query
          name: search
          schema:
            type: string
            minLength: 2
      responses:
        '200':
          description: Producer list response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Producer'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
  /regions:
    get:
      summary: List regions
      operationId: listRegions
      responses:
        '200':
          description: Region list response
  /grapes:
    get:
      summary: List grapes
      operationId: listGrapes
      responses:
        '200':
          description: Grape list response
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: "Bearer YOUR_API_KEY"
  schemas:
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        last_page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        from:
          type: integer
          nullable: true
        to:
          type: integer
          nullable: true
    Producer:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        title:
          type: string
          nullable: true
        display_name:
          type: string
          nullable: true
    Region:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        country:
          type: string
        language:
          type: string
    WineBase:
      type: object
      properties:
        id:
          type: integer
        display_name:
          type: string
        color:
          type: string
        type:
          type: string
        sub_type:
          type: string
          nullable: true
        residual_sugar:
          type: string
          nullable: true
        producer:
          $ref: '#/components/schemas/Producer'
        region:
          $ref: '#/components/schemas/Region'
    WineListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WineBase'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    WineSearchResult:
      type: object
      properties:
        id:
          type: integer
        display_name:
          type: string
        color:
          type: string
        residual_sugar:
          type: string
          nullable: true
        producer_name:
          type: string
          nullable: true
        producer_title:
          type: string
          nullable: true
        producer_display_name:
          type: string
          nullable: true
    WineDetails:
      allOf:
        - $ref: '#/components/schemas/WineBase'
        - type: object
          properties:
            grapes:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
            description:
              type: object
              nullable: true
              properties:
                text:
                  type: string
                  nullable: true
                text_long:
                  type: string
                  nullable: true
                language:
                  type: string
                  nullable: true
            pairing:
              type: object
              nullable: true
              properties:
                text:
                  type: string
                  nullable: true
                text_long:
                  type: string
                  nullable: true
                language:
                  type: string
                  nullable: true
            tasting_notes:
              type: object
              nullable: true
              properties:
                text:
                  type: string
                  nullable: true
                text_long:
                  type: string
                  nullable: true
                language:
                  type: string
                  nullable: true
            flavor_profile:
              type: object
              nullable: true
              properties:
                sweetness:
                  type: integer
                  nullable: true
                acidity:
                  type: integer
                  nullable: true
                tannins:
                  type: integer
                  nullable: true
                alcohol:
                  type: integer
                  nullable: true
                body:
                  type: integer
                  nullable: true
                finish:
                  type: integer
                  nullable: true
