Content Comparison

swagger: "2.0"
info:
  version: "0.0.1"
  title: ARES Kudo API server
# during dev, should point to your local machine
host: localhost:3000
# basePath prefixes all resource paths
basePath: /api
#
tags:
  - name: ARES Kudo Required
    description: Required APIs to load and store a drawing
  - name: ARES Kudo Optional
    description: Optional APIs to improve interactions for loading and storing a drawing
  - name: File Sessions
    description: Optional File Session Handling
  - name: Commenting
    description: API support for commenting panel
  - name: User Sessions
    description: Optional User Session Handling
  - name: Block Library
    description: API support for Block Library

schemes:
  # tip: remove http to make production-grade
  - http
  - https
# format of bodies a client can send (Content-Type)
consumes:
  - application/json
# format of the responses to the client (Accepts)
produces:
  - application/json
parameters:
  fileId:
    name: fileId
    in: path
    description: The id of the file
    required: true
    type: string
  libId:
    name: libId
    in: path
    description: The id of the library
    required: true
    type: string
  itemId:
    name: itemId
    in: path
    description: The id of the block
    required: true
    type: string
  ownerType:
    name: ownerType
    in: header
    description: Type of the library (PUBLIC/USER/ORG)
    required: false
    type: string
  sessionId:
    name: sessionid
    in: header
    description: the user sessionId
    required: true
    type: string
  threadId:
    name: threadId
    in: path
    description: the comment thread
    required: true
    type: string
  markupId:
    name: markupId
    in: path
    description: the markup
    required: true
    type: string
  commentId:
    name: commentId
    in: path
    description: the comment
    required: true
    type: string
  attachmentId:
    name: attachmentId
    in: path
    description: the attachment
    required: true
    type: string
  optionalSessionId:
    name: sessionid
    in: header
    description: the user sessionId
    required: false
    type: string
paths:
  /library/blocks:
    parameters:
      - $ref: "#/parameters/optionalSessionId"
      - $ref: "#/parameters/ownerType"

    x-swagger-router-controller: blocks

    get:
      description: Returns block libraries

      operationId: libraries_get
      tags:
        - Block Library
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/LibrariesResponse"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /library/blocks/{libId}/items:
    parameters:
      - $ref: "#/parameters/libId"
      - $ref: "#/parameters/optionalSessionId"

    x-swagger-router-controller: blocks

    get:
      description: Returns blocks of a library

      operationId: blocks_get
      tags:
        - Block Library
      responses:
        "200":
          description: Success
          schema:
            $ref: "#/definitions/BlocksResponse"
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /library/blocks/{libId}/items/{itemId}/content:
    parameters:
      - $ref: "#/parameters/libId"
      - $ref: "#/parameters/itemId"
      - $ref: "#/parameters/optionalSessionId"
      - in: query
        name: fileType
        required: false
        default: "dwg"
        type: string

    x-swagger-router-controller: blocks

    get:
      description: Returns block file

      operationId: block_getfile
      tags:
        - Block Library
      produces:
        - application/octet-stream
      responses:
        "200":
          description: Success
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /library/blocks/{libId}/items/{itemId}/thumbnail:
    parameters:
      - $ref: "#/parameters/libId"
      - $ref: "#/parameters/itemId"
      - $ref: "#/parameters/optionalSessionId"
      - in: query
        name: fileType
        required: false
        default: "png"
        type: string

    x-swagger-router-controller: blocks

    get:
      description: Returns block thumbnail

      operationId: block_getthumbnail
      tags:
        - Block Library
      produces:
        - application/octet-stream
      responses:
        "200":
          description: Success
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /files:
    parameters:
      - $ref: "#/parameters/optionalSessionId"
    x-swagger-router-controller: files
    post:
      description: Create/Update a file
      # used as the method name of the controller
      operationId: post_file
      tags:
        - ARES Kudo Required
      consumes:
        - multipart/form-data
      parameters:
        - in: header
          name: fileId
          description: ID of the file (New file will be created if this value is not specified)
          required: false
          type: string
        - in: formData
          name: file
          required: true
          type: file
      responses:
        "200":
          description: Success
          schema:
            required:
              - id
              - filename
              - isNewFile
              - changeId
            properties:
              id:
                type: string
              filename:
                type: string
              isNewFile:
                type: boolean
              changeId:
                type: string
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /files/{fileId}/data:
    parameters:
      - $ref: "#/parameters/fileId"
      - $ref: "#/parameters/optionalSessionId"
    # binds a127 app logic to a route
    x-swagger-router-controller: files

    get:
      description: Returns file content
      # used as the method name of the controller
      operationId: data_get
      tags:
        - ARES Kudo Required
      produces:
        - application/octet-stream
      responses:
        "200":
          description: Success
        # responses may fall through to errors
        "404":
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /files/{fileId}/xref/search:
    # binds a127 app logic to a route
    x-swagger-router-controller: files
    post:
      description: XRef search
      # used as the method name of the controller
      operationId: xref_search
      tags:
        - ARES Kudo Optional
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/optionalSessionId"
        - name: body
          in: body
          required: true
          schema:
            required:
              - path
            properties:
              path:
                type: array
                description: xrefs paths to search
                items:
                  type: string
      responses:
        "200":
          description: Success
          schema:
            type: array
            items:
              type: object
              properties:
                path:
                  type: string
                files:
                  type: array
                  items:
                    type: object
                    properties:
                      "_id":
                        type: string
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /files/{fileId}/preview:
    # binds a127 app logic to a route
    x-swagger-router-controller: files
    post:
      description: Optionally handle receiving updates previews
      # used as the method name of the controller
      operationId: preview_post
      tags:
        - ARES Kudo Optional
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/optionalSessionId"
        - in: formData
          name: file
          required: true
          type: file
      responses:
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /files/{fileId}/info:
    # binds a127 app logic to a route
    x-swagger-router-controller: files
    get:
      description: Returns file information
      # used as the method name of the controller
      operationId: info_get
      tags:
        - ARES Kudo Required
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/optionalSessionId"
      responses:
        "200":
          description: Success
          schema:
            required:
              - status
            type: object
            properties:
              status:
                type: string
                default: "ok"
              filename:
                type: string
              folderId:
                type: string
              owner:
                type: string
        # responses may fall through to errors
        "401":
          description: User is not autenticated
          schema:
            $ref: "#/definitions/ErrorResponse"
        "404":
          description: File is not found
          schema:
            $ref: "#/definitions/ErrorResponse"
  /files/{fileId}/session:
    # binds a127 app logic to a route
    parameters:
      - $ref: "#/parameters/fileId"
      - $ref: "#/parameters/sessionId"

    x-swagger-router-controller: files_sessions
    get:
      description: get file sessions
      # used as the method name of the controller
      operationId: session_get
      tags:
        - File Sessions
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/SessionsResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
    post:
      description: Create file session. Sessions need to be either of type "view" or "edit"
      # used as the method name of the controller
      operationId: session_post
      tags:
        - File Sessions
      parameters:
        - name: body
          in: body
          required: true
          schema:
            required:
              - mode
            properties:
              mode:
                type: string
                description: Type of session requested
                enum: [view, edit]
              fileId:
                type: string
                description: fileId for the file for which the session is being requested
      responses:
        "200":
          description: Success
          schema:
            required:
              - status
              - "_id"
            properties:
              status:
                type: string
                default: "ok"
              "_id":
                type: string
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
    delete:
      description: delete file session
      # used as the method name of the controller
      operationId: session_delete
      parameters:
        - name: body
          in: body
          required: true
          schema:
            required:
              - mode
            properties:
              mode:
                type: string
                description: Type of session requested
                enum: [view, edit]
      tags:
        - File Sessions
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/SessionsResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /auth:
    # binds a127 app logic to a route
    x-swagger-router-controller: auth
    get:
      description: validate user session
      # used as the method name of the controller
      tags:
        - User Sessions
      operationId: auth_get
      parameters:
        - $ref: "#/parameters/optionalSessionId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
        401:
          description: Authorization information is missing or invalid.
  /users:
    # binds a127 app logic to a route
    x-swagger-router-controller: users
    get:
      description: Returns user object
      # used as the method name of the controller
      operationId: users_get
      tags:
        - User Sessions
      parameters:
        - $ref: "#/parameters/sessionId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              results:
                type: array
                items:
                  type: object
                  properties:
                    fname:
                      type: string
                      description: first name
                    surname:
                      type: string
                      description: last name of user
                    "_id":
                      type: string
                    email:
                      type: string
                    licenseExpirationDate:
                      type: integer
                    preferences:
                      type: object
                      properties:
                        preferences_display:
                          type: object
                          properties:
                            graphicswinmodelbackgrndcolor:
                              type: string
                              default: White
                        view:
                          type: object
                        window:
                          type: object
                        variables:
                          type: object
                          properties:
                            dynasnap:
                              type: string
                              default: "63"
    put:
      description: Returns user object
      # used as the method name of the controller
      operationId: users_put
      tags:
        - User Sessions
      parameters:
        - $ref: "#/parameters/sessionId"
        - name: body
          in: body
          required: true
          schema:
            properties:
              preferences:
                type: object
                description: user preferences
                properties:
                  window:
                    type: object
                    properties:
                      edit:
                        type: object
                        properties:
                          dockwidgets:
                            type: object
                            properties:
                              layerwindow:
                                type: object
                                properties:
                                  h:
                                    type: string
                                    description: height o the layerwindow

      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
  /v1/files/{fileId}/annotations:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    get:
      description: Returns annotations for a file
      # used as the method name of the controller
      operationId: annotations_get
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - name: timestamp
          type: integer
          in: query
          required: false
          description: timestamp of last request to only send new items
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              results:
                type: object
                properties:
                  timestamp:
                    type: integer
                    description: time of response
                  commmentThreads:
                    type: array
                    description: ""
                    items:
                      type: object
                  markups:
                    type: array
                    description: ""
                    items:
                      type: object
                  status:
                    type: string
                    default: "ok"
  /v1/files/{fileId}/markups:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    get:
      description: Returns markups for a file
      # used as the method name of the controller
      operationId: markups_get
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - name: timestamp
          type: integer
          in: query
          required: false
          description: timestamp of last request to only send new items
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              results:
                type: object
                properties:
                  timestamp:
                    type: integer
                    description: time of response
                  markups:
                    type: array
                    description: ""
                    items:
                      type: object
                  status:
                    type: string
                    default: "ok"
  /v1/files/{fileId}/commentThreads:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    get:
      description: Returns comments for a file
      # used as the method name of the controller
      operationId: commentThreads_get
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - name: timestamp
          type: integer
          in: query
          required: false
          description: timestamp of last request to only send new items
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              results:
                type: object
                properties:
                  timestamp:
                    type: integer
                    description: time of response
                  commmentThreads:
                    type: array
                    description: ""
                    items:
                      type: object
                  status:
                    type: string
                    default: "ok"
  /v1/files/{fileId}/commentThread:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    post:
      description: Add a new commentThread for a file
      # used as the method name of the controller
      operationId: commentThread_post
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              title:
                type: string
              text:
                type: string
              state:
                type: string
                enum: [ACTIVE, RESOLVED]
              ids:
                type: array
                items:
                  type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/commentThread/{threadId}:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    put:
      description: Update a commentThread
      # used as the method name of the controller
      operationId: commentThread_put
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/threadId"
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              title:
                type: string
              text:
                type: string
              ids:
                type: array
                items:
                  type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    get:
      description: get a commentThread
      # used as the method name of the controller
      operationId: commentThread_get
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/threadId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    delete:
      description: Delete a comment Thread
      # used as the method name of the controller
      operationId: commentThread_delete
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/threadId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/commentThread/{threadId}/comment/{commentId}:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    put:
      description: Update a comment
      # used as the method name of the controller
      operationId: comment_put
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/threadId"
        - $ref: "#/parameters/commentId"
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              text:
                type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    get:
      description: Retrieve a comment
      # used as the method name of the controller
      operationId: comment_get
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/threadId"
        - $ref: "#/parameters/commentId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    delete:
      description: Delete a comment
      # used as the method name of the controller
      operationId: comment_delete
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/threadId"
        - $ref: "#/parameters/commentId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/commentThread/{threadId}/comment:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    post:
      description: Post a new comment
      # used as the method name of the controller
      operationId: comment_post
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/threadId"
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              text:
                type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/markup:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    post:
      description: Add a new markup for a file
      # used as the method name of the controller
      operationId: markup_post
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              title:
                type: string
              text:
                type: string
              state:
                type: string
                enum: [ACTIVE, RESOLVED]
              ids:
                type: array
                items:
                  type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/markup/{markupId}:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    put:
      description: Update a markup
      # used as the method name of the controller
      operationId: markup_put
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/markupId"
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              title:
                type: string
              text:
                type: string
              ids:
                type: array
                items:
                  type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    get:
      description: get a markup
      # used as the method name of the controller
      operationId: markup_get
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/markupId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    delete:
      description: delete a markup
      # used as the method name of the controller
      operationId: markup_delete
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/markupId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/markup/{markupId}/comment/{commentId}:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    put:
      description: Update a comment
      # used as the method name of the controller
      operationId: markupcomment_put
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/markupId"
        - $ref: "#/parameters/commentId"
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              text:
                type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    get:
      description: Retrieve a markup comment
      # used as the method name of the controller
      operationId: markupcomment_get
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/markupId"
        - $ref: "#/parameters/commentId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    delete:
      description: Delete a markup comment
      # used as the method name of the controller
      operationId: markupcomment_delete
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/markupId"
        - $ref: "#/parameters/commentId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/markup/{markupId}/comment:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    post:
      description: Post a new markup comment
      # used as the method name of the controller
      operationId: markupcomment_post
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/markupId"
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              text:
                type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/attachment:
    x-swagger-router-controller: comments
    post:
      description: Create a markup attachment
      # used as the method name of the controller
      operationId: attachment_post
      tags:
        - Commenting
      consumes:
        - multipart/form-data
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - in: formData
          name: attachment
          required: true
          type: file
      responses:
        "200":
          description: Success
          schema:
            required:
              - status
              - changeId
            properties:
              status:
                type: string
                default: "ok"
              changeId:
                type: string
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /v1/files/{fileId}/attachments:
    x-swagger-router-controller: comments
    get:
      description: Retrieve all attachments
      # used as the method name of the controller
      operationId: attachments_get
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/attachments/{attachmentId}:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    get:
      description: Retrieve attachment
      # used as the method name of the controller
      operationId: attachment_get
      tags:
        - Commenting
      parameters:
        - $ref: "#/parameters/fileId"
        - $ref: "#/parameters/sessionId"
        - $ref: "#/parameters/attachmentId"
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status:
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /swagger:
    x-swagger-pipe: swagger_raw
# complex objects have schema definitions
definitions:
  SessionsResponse:
    required:
      - status
      - results
    properties:
      status:
        type: string
        default: "ok"
      results:
        type: array
        items:
          type: object
          properties:
            mode:
              type: string
              enum: [view, edit]
            username:
              type: string
            sessionId:
              type: string
            userId:
              type: string

  LibrariesResponse:
    required:
      - status
      - results
    properties:
      status:
        type: string
        default: "ok"
      results:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
  BlocksResponse:
    required:
      - status
      - results
    properties:
      status:
        type: string
        default: "ok"
      results:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            thumbnail:
              type: string

  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string
      errrorId:
        type: string