asyncapi: 3.0.0
info:
  title: adaptor:ex socket.io plugin API
  description: 
    Subscribe and publish to socket.io message streams via the adaptorex socketio plugin actions.<br><br>
    Messages that can be subscribed to via socket.on() might include metadata "action", "state", "timestamp", "id" and "payload" whereas "payload" contains whatever is described under payload.
  version: 1.0.0
servers:
  development:
    host: '{domain}:{port}/game/{game}/socketio'
    protocol: ws
    description: Custom server
    variables:
      domain:
        default: 'localhost'
      port:
        default: '8080'
      game:
        default: 'MyGame'
        $ref: '#/components/parameters/game'
channels:
  namespace:
    address: '/{namespace}'
    parameters:
      namespace:
        description: Name of a Namespace created in socketio plugin settings
    messages:
      join:
        description: join a room that has been opened with `create` beforehand
        payload:
          description: the room id string
          type: string
      joined:
        payload:
          type: object
          properties:
            status:
              type: number
              const: 200
            data:
              description: Data associated with room including room id, status etc.
              type: object
      leave:
        description: leave a room that has been joined beforehand
        payload:
          description: the room id string. Send `all` to leave all rooms that have been joined.
          type: string
      create:
        summary: Create a new room that can be joined.
        description: Create a new room to join. If Namespace item settings define a level and or 
                     level arguments, 'create' will start a session with an item with the below payload.
                     If namespace settings define an item collection as argument a new item will be created.
                     You can provide more properties for the newly created item by adding them to the payload.
                     Use empty string or an empty id property to assign an auto generated id value. The new id
                     will be returned if you use socketio emitWithAck or add a callback.
        payload:
          type: 
            - object
            - string
          properties:
            id:
              type: string
              description: unique name of room
            name:
              type: string
              description: optional name of item that will be added to the collection defined in socketio plugin settings
          additionalProperties: true
      created:
        payload:
          type: object
          properties: 
            status: 
              type: number
              const: 201
            id:
              type: string
      error:
        payload:
          description: An Error occurred.
          type: object
          properties:
            status:
              type: number
              enum: [400, 404, 500]
            name:
              type: string
            message:
              type: string
            stack:
              type: string
operations:
  join:
    action: 'send'
    description: "Note: Use socketio emitWithAck to get the operations reply."
    channel:
      $ref: '#/channels/namespace'
    messages:
      - $ref: '#/channels/namespace/messages/join'
    reply:
      channel:
        $ref: '#/channels/namespace'
      messages:
        - $ref: '#/channels/namespace/messages/joined'
        - $ref: '#/channels/namespace/messages/error'
  create:
    action: 'send'
    description: "If a room has been created, it is joined automatically. Note: Use socketio emitWithAck to get the operations reply."
    channel:
      $ref: '#/channels/namespace'
    messages:
      - $ref: '#/channels/namespace/messages/create'
    reply:
      channel:
        $ref: '#/channels/namespace'
      messages:
        - $ref: '#/channels/namespace/messages/created'
        - $ref: '#/channels/namespace/messages/error'
  leave:
    action: 'send'
    channel:
      $ref: '#/channels/namespace'
    messages:
      - $ref: '#/channels/namespace/messages/leave'
components:
  parameters:
    game:
      description: game name
  schemas:
    meta:
      type: object
      properties:
        id:
          type: string
          description: A short unique id for this message
        action:
          type: object
          description: information about the action the message was send by
        state:
          type: object
          description: information about the state the message was sent within
        timestamp:
          description: UNIX-Timestamp of time a message was published
          type: number