labelelec/openapi.yaml

openapi: 3.0.3
info:
  title: Label Printer API
  description: API voor het beheren, afdrukken en downloaden van etiketten/labels via gLabels en CUPS.
  version: 1.0.0
servers:
  - url: http://localhost:3000
    description: Lokale ontwikkelaars-server
paths:
  /labels:
    get:
      summary: Haal een lijst op van alle beschikbare labels en hun velden
      operationId: getLabels
      responses:
        '200':
          description: Succesvol ophalen van labels
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LabelInfo'
        '500':
          description: Serverfout bij ophalen labels
          content:
            text/plain:
              schema:
                type: string
                example: "Fout bij ophalen labels: ..."

  /print:
    post:
      summary: Verstuur een label printopdracht naar de CUPS printer
      operationId: printLabel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintRequest'
      responses:
        '200':
          description: Afdrukopdracht succesvol verzonden
          content:
            text/plain:
              schema:
                type: string
                example: "Labels geprint!"
        '404':
          description: Label sjabloon niet gevonden
          content:
            text/plain:
              schema:
                type: string
                example: "Label adres niet gevonden."
        '500':
          description: Fout bij genereren of afdrukken van de labels
          content:
            text/plain:
              schema:
                type: string
                example: "Print fout: ..."

  /download:
    post:
      summary: Genereer en bekijk/download het gegenereerde label als PDF of PNG afbeelding
      operationId: downloadLabel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DownloadRequest'
      responses:
        '200':
          description: Het gegenereerde label in PDF of PNG formaat
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        '404':
          description: Label sjabloon niet gevonden
          content:
            text/plain:
              schema:
                type: string
                example: "Label adres niet gevonden."
        '500':
          description: Fout bij genereren of converteren van het label
          content:
            text/plain:
              schema:
                type: string
                example: "Fout: ..."

components:
  schemas:
    LabelInfo:
      type: object
      required:
        - name
        - fields
      properties:
        name:
          type: string
          description: Naam van het labelbestand (zonder .glabels extensie)
          example: etenopslag
        fields:
          type: array
          description: Lijst van dynamische variabelen in het sjabloon
          items:
            type: string
          example: ["Product", "Datum"]

    LabelDataPayload:
      type: object
      required:
        - labelName
      properties:
        labelName:
          type: string
          description: Naam van het sjabloon
          example: etenopslag
        headers:
          type: array
          description: Kolomkoppen voor de samenvoeggegevens (CSV headers)
          items:
            type: string
          example: ["Product", "Datum"]
        data:
          type: array
          description: Rijen met gegevens corresponderend met de headers
          items:
            type: array
            items:
              type: string
          example: [["Aardappelpuree", "15-04-2026"]]

    PrintRequest:
      allOf:
        - $ref: '#/components/schemas/LabelDataPayload'
        - type: object
          properties:
            copies:
              type: integer
              minimum: 1
              default: 1
              description: Aantal af te drukken kopieën
              example: 2

    DownloadRequest:
      allOf:
        - $ref: '#/components/schemas/LabelDataPayload'
        - type: object
          properties:
            format:
              type: string
              enum: [pdf, png]
              default: pdf
              description: Gewenste uitvoerformaat (pdf of png)
              example: png
            rotate:
              type: number
              default: 0
              description: Rotatie in graden bij png formaat (bijv. 270)
              example: 270