openapi: 3.0.3
info:
  title: Menu API - V1
  version: 1.1.0
  description: API for querying category menus and taxonomy.
  contact:
    name: SharinApp Team

servers:
  - url: https://api-staging.sharin.app
    description: Staging server (pre-production)
  - url: https://api.sharin.app
    description: Production server
  - url: http://api.sharinapp.local
    description: Local development server (used in tests)

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key required for all requests
  parameters:
    DepthParam:
      name: depth
      in: query
      required: false
      description: Maximum depth of the category tree
      schema:
        type: integer
        minimum: 1
        maximum: 4
        example: 4
    ActAsCategoryParam:
      name: act_as_category
      in: query
      required: false
      schema:
        type: string
        maxLength: 1
        enum: ['Y', 'N']
      description: Extract only tags treated as categories
      example: "N"
    CategoryCodeParam:
      name: category_code
      in: path
      required: true
      description: Category identifier
      schema:
        type: string
  schemas:
    SuccessResponse:
      type: object
      required: [meta, data]
      properties:
        data:
          type: array
          oneOf:
            - $ref: '#/components/schemas/Category'
            - $ref: '#/components/schemas/Tags'
        meta:
          allOf:
            - $ref: './schemas/CommonSchemas.yaml#/MetaDefaultResponse'
    Category:
      title: Category
      type: object
      properties:
        key:
          type: string
          description: Path hash
          example: "abc123"
        path:
          type: string
          description: URL path
          example: "/electronics/smartphones"
        label:
          type: string
          description: Category name
          example: "Electronics"
        location:
          type: string
          description: Full (relative) path
          example: "Electronics > Smartphones"
        children:
          type: array
          items:
            $ref: '#/components/schemas/Category'
          description: Sub-categories
        has_children:
          type: boolean
          description: Whether it has sub-categories
          example: true
        product_count:
          type: integer
          description: Number of products in the category
          example: 42
    Tags:
      title: Tags
      type: object
      properties:
        code:
          type: string
          example: "7c86834f1819f8c0ec3c03ed16470a83"
        label:
          type: string
          description: Tag name
          example: "Home and Lifestyle"
        icon_uri:
          type: string
          format: uri
          example: https://cdn.sharinapp.com/assets/icon.svg
        act_as_catalogue:
          type: string
          enum: ['Y', 'N']
          required: false
          description: Whether the tag is also treated as a catalogue
          example: "N"
    ErrorResponse:
      $ref: './schemas/CommonSchemas.yaml#/ErrorResponse'

paths:
  /v1/menu/categories:
    get:
      tags: [Categories]
      summary: Retrieve all categories
      description: |
        Returns the list of all categories containing items,
        organized in a hierarchical structure.
      operationId: getCategories
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
        - $ref: '#/components/parameters/DepthParam'
      responses:
        '200':
          description: List of categories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/menu/categories/{category_code}:
    get:
      tags: [Categories]
      summary: Recupera una singola categoria
      description: |
        Restituisce i dettagli di una categoria specifica restituendo
        l'elenco di tutte le proprie sotto-categorie che contengono articoli,
        organizzate in struttura gerarchica.
      operationId: getCategoryByCode
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
        - $ref: '#/components/parameters/CategoryCodeParam'
      responses:
        '200':
          description: Dettagli della categoria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Errore nella richiesta
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/menu/taxonomy:
    get:
      tags: [Taxonomy]
      summary: Retrieve the complete taxonomy
      description: |
        Returns the complete taxonomy, including both categories with items and those without, organized in hierarchical structures.
      operationId: getTaxonomy
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
        - $ref: '#/components/parameters/DepthParam'
      responses:
        '200':
          description: Complete taxonomy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  # 1.1.0
  /v1/menu/tags:
    get:
      tags: [Tags]
      summary: Retrieve the complete tag list
      description: |
        Returns the full list of tags, including both entity-related tags and unlinked ones.
      operationId: getTags
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
        - $ref: '#/components/parameters/ActAsCategoryParam'
      responses:
        '200':
          description: Complete list of tags
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'