swagger.yaml

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

swagger: '2.0'
info:
  title: S2S API
  version: "0.1"
consumes:
  - application/json
produces:
  - application/json
basePath: /api
#security:
  # enable OAuth protection for all REST endpoints
  # (only active if the TOKENINFO_URL environment variable is set)
#  - oauth2: [uid]

# a simple data path:
paths:
  /translate:
    get:
      tags: [Translate, All]
      operationId: server.get_translation
      summary: Get Translation and Data for sentence
      parameters:
        - $ref: '#/parameters/inSentence'
        - $ref: '#/parameters/neighbors'
        - $ref: '#/parameters/partial'
        - $ref: '#/parameters/force_attn'
      responses:
        200:
          description: Return Translation and meta data
          schema:
            $ref: '#/definitions/Translation'
  /translate_compare:
    get:
      tags: [Translate, Neighbors, All]
      operationId: server.get_translation_compare
      summary: Two-way comparison between two sentences with merged vector-spaces
      parameters:
        - $ref: '#/parameters/inSentence'
        - $ref: '#/parameters/compareSentence'
        - $ref: '#/parameters/neighbors'
      responses:
        200:
          description: fun
  /project_info:
    get:
      tags: [All]
      operationId: server.get_info
      summary: get general project informations
      parameters:
        - $ref: '#/parameters/project_id'
      responses:
        200:
          description: fun
#  /compare_translation:
#    get:
#      tags: [Translate, All]
#      operationId: server.compare_translation
#      summary: Compare Translation and Data for sentences
#      parameters:
#        - $ref: '#/parameters/inSentence'
#        - $ref: '#/parameters/compareSentences'
#        - $ref: '#/parameters/partial'
#      responses:
#        200:
#          description: Return Translations and distances
#          schema:
#            $ref: '#/definitions/Translation'
  /close_words:
    get:
      tags: [Embedding, All]
      operationId: server.get_close_words
      summary: Get the closest words w.r.t word embedding
      parameters:
        - $ref: '#/parameters/inWord'
        - $ref: '#/parameters/loc'
        - $ref: '#/parameters/p_method'
        - $ref: '#/parameters/limit'
      responses:
        200:
          description: Return list of closest words

  /close_vectors:
    get:
      tags: [Embedding, All]
      operationId: server.get_close_vectors
      summary: Find closesest vector to vector at position
      parameters:
        - $ref: '#/parameters/vector_name'
        - $ref: '#/parameters/indices'
      responses:
        200:
          description: return list of indices

  /neighbor_details:
    get:
      tags: [Embedding, All]
      operationId: server.get_neighbor_details
      summary: Get details about close neighbors
      parameters:
        - $ref: '#/parameters/vector_name'
        - $ref: '#/parameters/indices'
        - $ref: '#/parameters/p_method'
      responses:
        200:
          description: return list details

  /train_data_for_index:
    get:
      tags: [Index, All]
      operationId: server.train_data_for_index
      summary: Get data from training set for specific index id
      parameters:
        - $ref: '#/parameters/indices'
        - $ref: '#/parameters/loc'
      responses:
        200:
          description: return list details

parameters:
  inSentence:
    name: in
    description: the input sentence
    in: query
    type: string
    default:  "world"
  compareSentence:
    name: compare
    description: compare sentence
    in: query
    type: string
  compareSentences:
    name: compare
    description: list of sentences to compare against (tab seperated !!)
    in: query
    required: true
    type: array
    collectionFormat: pipes
    items:
      type: string
  inWord:
    name: in
    description: the input word
    in: query
    type: string
    default: "hello"
  loc:
    name: loc
    description: location - src or tgt
    in: query
    type: string
    enum:
      - "src"
      - "tgt"
    default: "src"
  limit:
    name: limit
    description: limit of results
    in: query
    type: integer
    default: 100
  p_method:
    name: p_method
    description: projection method to use
    in: query
    type: string
    enum:
      - "mds"
      - "pca"
      - "tsne"
      - "none"
    default: "pca"
  vector_name:
    name: vector_name
    description: Name of the vector -- encoder, embedding, etc...
    in: query
    type: string
    default: "context"
  index:
    name: index
    in: query
    description: position in corpus
    type: integer
    default: 100
  indices:
    name: indices
    in: query
    description: positions in corpus
    type: array
    items:
      type: integer
    required: true
  neighbors:
    name: neighbors
    description: list of dimensions to add neighbors to
    in: query
    type: array
    items:
      type: string
    required: false
  partial:
    name: partial
    description: partial translate for decoder
    in: query
    type: array
    collectionFormat: pipes
    items:
      type: string
    required: false
  force_attn:
    name: force_attn
    description: force attention
    in: query
    type: array
    items:
      type: integer
    required: false
  project_id:
    name: project_id
    description: Project ID
    in: query
    type: string
    required: false


# These definitions are only needed for proper documentation
# no functional purpose
definitions:
  Translation:
    type: object
    required:
      - in
      - out
      - attn
    properties:
      in:
        type: string
        description: input sentence
        example: "The sun is yellow ."
      out:
        type: string
        description: translated sentence
        example: "Die Sonne ist gelb ."
      attn:
        type: array
        description: Attention for each output position
        example: [[.1,.2,.13],[.3,.4,.2]]
        items:
          type: integer




#securityDefinitions:
#  oauth2:
#    type: oauth2
#    flow: implicit
#    authorizationUrl: https://example.com/oauth2/dialog
#    scopes:
#      uid: Unique identifier of the user accessing the service.