swagger.yaml

openapi: 3.0.0
info:
  description: "This a definition of API for communication with MOZART hardware."
  version: "1.0.0"
  title: "MOZART Low-level API"
tags:
- name: "Configuration"
  description: "Stuff for setting things up"
- name: "Control"
  description: "Controlling and monitoring the thing"

paths:
  /motions/{motionId}/execute:
    post:
      tags:
      - "Control"
      summary: "Triggers execution of predefined motion."
      parameters:
      - name: "motionId"
        in: "path"
        description: "ID of the motion."
        required: true
        schema:
          type: "integer"
          format: "int64"
      responses:
        '204':
          description: "Motion successfully started"
  /motions:
    get:
      tags:
        - "Configuration"
      summary: "Returns a list of available motion types"
      responses:
        200:
          description: "List of motions"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  oneOf:
                    - $ref: '#/components/schemas/Motion'
                    - $ref: '#/components/schemas/TranslateMotion'
                  discriminator:
                    propertyName: motionType
  /motion/status:
    get:
      summary: "Returns the current status"
      description: "Indicates whether the system is executing a motion or waiting for a command."
      tags:
      - "Control"
      responses:
        '200':
          description: "The current status of the motion system"
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  status:
                    type: "string"
                    description: "Current status of the system"
                    enum:
                      - executing
                      - idle
                  motionId:
                    type: "integer"
                    format: "int64"
                    description: "The ID of the motion currently being executed, if applicable."
                    nullable: true

components:
  schemas:
    Vector3:
      type: "object"
      properties:
        x:
          type: number
        y:
          type: number
        z:
          type: number
    Quaternion:
      type: "object"
      properties:
        x:
          type: number
        y:
          type: number
        z:
          type: number
        w:
          type: number
    Motion:
      type: "object"
      description: Defines basic metadata about known motion primitive.
      properties:
        id:
          type: "integer"
          format: "int64"
        motionType:
          type: "string"
    TranslateMotion:
        allOf:     # Combines the Motion and the inline model
          - $ref: '#/components/schemas/Motion'
          - $ref: '#/components/schemas/Vector3'