openapi: 3.0.0
info:
  title: "BarCode and QRCode generator and decoder"
  version: '1.0'
  description: "Generates and decodes BarCodes and QRCodes."
  contact:
    email: qrbarcode-api@intami.pl
externalDocs:
  description: "API home page"
  url: "https://qrbar-code.intami.pl/index.html"
servers:
  - url: 'https://qrbar-code.intami.pl'
#  - url: 'http://localhost:8088'
paths:
  '/decode':
    post:
      summary: "Decode QRCodes and BarCodes form an image"
      requestBody:
        description: "image or pdf binary content"
        required: true
        content:
          image/png:
            schema:
              type: string
              format: binary
          image/gif:
            schema:
              type: string
              format: binary
          image/tiff:
            schema:
              type: string
              format: binary
          image/webp:
            schema:
              type: string
              format: binary
          image/jpeg:
            schema:
              type: string
              format: binary
          image/bmp:
            schema:
              type: string
              format: binary
          application/pdf:
            schema:
              type: string
              format: binary
      responses:
        "200":
          description: "Information about detected codes"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecodedCodeResponse"
        "422":
          description: "If payload is not valid image nor pdf"
  '/generate/bar/{barCodeType}':
    parameters:
      - name: "barCodeType"
        required: true
        description: "BarCode type to generate"
        example: "code93"
        in: path
        schema:
          type: string
          enum:
            - "twooffive"
            - "code93"
            - "code128"
            - "code39"
            - "ean"
            - "ean13"
            - "aztec"
            - "pdf417"
            - "codabar"
            - "datamatrix"
    post:
      parameters:
        - $ref: "#/components/parameters/Accept"
        - $ref: "#/components/parameters/X-TraceId"
      summary: "Generate BarCode"
      requestBody:
        description: "BarCode definition"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BarCodeRequest"
      responses:
        "201":
          description: "Generated QRCode"
          content:
            image/png:
              schema:
                type: string
                format: binary
  '/generate/qr/text':
    post:
      parameters:
        - $ref: "#/components/parameters/Accept"
        - $ref: "#/components/parameters/X-TraceId"
      summary: "Generate text QRCode"
      requestBody:
        description: "definition of QRCode"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QrCodeRequestText"
      responses:
        "201":
          description: "Generated QRCode"
          content:
            image/png:
              schema:
                type: string
                format: binary
  '/generate/qr/url':
    post:
      parameters:
        - $ref: "#/components/parameters/Accept"
        - $ref: "#/components/parameters/X-TraceId"
      summary: "Generate website url QR code"
      requestBody:
        description: "Definition of QRCode"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QrCodeRequestURL"
      responses:
        "201":
          description: "Generated QRCode"
          content:
            image/png:
              schema:
                type: string
                format: binary
  '/generate/qr/wifi':
    post:
      parameters:
        - $ref: "#/components/parameters/Accept"
        - $ref: "#/components/parameters/X-TraceId"
      summary: "Generate wifi access QR code"
      requestBody:
        description: "Definition of QRCode"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QrCodeRequestWifi"
      responses:
        "201":
          description: "Generated QRCode"
          content:
            image/png:
              schema:
                type: string
                format: binary
  '/generate/qr/tel':
    post:
      parameters:
        - $ref: "#/components/parameters/Accept"
        - $ref: "#/components/parameters/X-TraceId"
      summary: "Generate phone number QR code"
      requestBody:
        description: "Definition of QRCode"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QrCodeRequestTel"
      responses:
        "201":
          description: "Generated QRCode"
          content:
            image/png:
              schema:
                type: string
                format: binary

components:
  schemas:
    DecodedCodeResponse:
      description: "Array of QRCode or BarCode descriptions"
      type: array
      items:
        $ref: "#/components/schemas/DecodedCodeItem"
    DecodedCodeItem:
      title: "Object describes detected bar and qr codes"
      type: object
      required:
        - content
      properties:
        content:
          description: "Decoded code content"
          type: string
        meta:
          description: "Bar or QR code meta information"
          type: object
          properties:
            codeType:
              type: string
              enum:
                - qrCode
                - barCode
              description: "Type of detected code"
            format:
              type: string
              description: "Format of detected code"
            pdfPage:
              type: integer
              description: "Number pf pdf page where the code was found"
              title: "Pdf page number"
    BarCodeRequest:
      title: "BarCode to generate definition"
      type: object
      properties:
        data:
          description: "Data to encode"
          type: string
          example: "123456789012"
        width:
          description: "BarCode width in pixels"
          type: integer
          default: 300
          example: 300
        height:
          description: "BarCode height in pixels"
          type: integer
          default: 100
          example: 100
      required:
        - data
    QrCodeRequest:
      title: "QRCode definition common for all QRCodes"
      type: object
      properties:
        backgroundColor:
          type: string
          description: "Background color in format #RGBA or #RGB"
          default: "#ffffff00"
        foregroundColor:
          type: string
          description: "Foreground color in format #RGBA or #RGB"
          default: "#00000000"
          example: "#000000"
        withBorder:
          type: boolean
          description: "If generate border around qr code"
          default: false
          example: false
        errorRecovery:
          type: string
          enum:
            - "low"
            - "medium"
            - "high"
            - "highest"
          description: "Error correction level in qr code"
          default: "medium"
          example: "medium"
        size:
          type: integer
          description: "Requested size of an image in pixels"
          default: 256
          example: 256
    QrCodeRequestText:
      allOf: # Combines the QrCodeRequest and the inline model
        - $ref: "#/components/schemas/QrCodeRequest"
        - type: object
          required:
            - text
          properties:
            text:
              type: string
              description: "Text of the QRCode"
              example: "Hello from QR Code."
    QrCodeRequestURL:
      allOf: # Combines the QrCodeRequest and the inline model
        - $ref: "#/components/schemas/QrCodeRequest"
        - type: object
          required:
            - url
          properties:
            url:
              type: string
              description: "Your website url"
              example: "https://your-website.com"
    QrCodeRequestTel:
      allOf: # Combines the QrCodeRequest and the inline model
        - $ref: "#/components/schemas/QrCodeRequest"
        - type: object
          required:
            - tel
          properties:
            tel:
              type: string
              description: "Phone number"
              example: "+22394595931"
    QrCodeRequestWifi:
      allOf: # Combines the QrCodeRequest and the inline model
        - $ref: "#/components/schemas/QrCodeRequest"
        - type: object
          required:
            - sid
            - security
          properties:
            sid:
              type: string
              description: "Wifi network sid"
              example: "WiFiName"
            security:
              type: string
              description: "Network security type"
              enum:
                - "WEP"
                - "WPA"
                - "WPA2-EAP"
                - "nopass"
              example: "WEP"
            password:
              type: string
              description: "Wifi password"
              example: "secret123"
            hidden:
              type: boolean
              description: "If network is hidden"
              example: false
              default: false

  parameters:
    X-TraceId:
      name: X-TraceId
      required: false
      in: header
      description: "TraceId that is copied to API response header"
      schema:
        type: string
        example: "optional_abc123"
    Accept:
      name: Accept
      required: true
      in: header
      description: "Requested format of the image"
      schema:
        type: string
        enum:
          - "image/png"
          - "image/gif"
          - "image/jpeg"
          - "image/webp"
          - "image/bmp"
          - "image/tiff"
          - "application/pdf"
          - "image/png;base64"
        example: "image/png"
        default: "image/png"
  headers:
    X-TraceId:
      required: false
      schema:
        type: string
        example: "abc123"
      description: if request contains X-TraceId header the value will be copied here
