# see also: https://github.com/hjacobs/connexion-example

swagger: '2.0'
info:
  title: BERT-viz API
  version: "0.0.1"
consumes:
  - application/json
produces:
  - application/json
basePath: /api

# ===============================================================================
## DEFINE API ##
# ===============================================================================
paths:

  /get-model-details:
    get:
      tags: [All]
      operationId: main.get_model_details
      summary: Get necessary information about the model, such as number of layers and heads
      parameters:
        - name: model
          description: Short string representing pretrained model, such as 'bert-base-uncased'
          in: query
          type: string
      responses:
        200:
          description: Returns information about the model

  /attend+meta:
    get:
      tags: [All]
      operationId: main.get_attentions_and_preds
      summary: Get the attention information, BERT Embeddings, and spacy meta info for an input sentence
      parameters:
        - name: model
          description: Which pretrained transformer information is requested from
          in: query
          type: string
        - name: sentence
          description: Sentence to analyze
          in: query
          type: string
        - name: layer
          description: Layer to get attentions at
          in: query
          type: number
      responses:
        200:
          description: Returns attentions, embeddings, and metadata

  /update-mask:
    post:
      tags: [All]
      operationId: main.update_masked_attention
      summary: Get the masked attention information of tokens given indices to mask
      parameters:
        - name: payload
          description: Main contents
          in: body
          schema:
            $ref: '#/definitions/maskPayload'
      responses:
        200:
          description: Update BERT's masked behavior for passed tokens


definitions:
  maskPayload:
    type: object
    properties:
      model: 
        type: string
        description: Which model to get results from
      tokens:
        type: array
        items: 
          type: string
        description: Main sentence tokens to analyze
      sentence:
        type: string
        description: The original sentence the tokens came from, for extracting metadata
      mask:
        type: array
        items: 
          type: number
        description: Indices of tokens to mask
      layer:
        type: number
        description: Layer to get results for
      
    required:
      - model
      - tokens
      - sentence
      - mask
      - layer