swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector DictionaryExamples API
schemes:
- https
tags:
- name: DictionaryExamples
paths:
  /Dictionary/Examples:
    post:
      description: Provides examples that show how terms in the dictionary are used in context. This operation is used in tandem with `Dictionary lookup`.<br>
      tags:
      - DictionaryExamples
      operationId: microsoftAzureTranslatorDictionaryexamples
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/ApiVersion'
      - name: from
        description: Specifies the language of the input text. The source language must be one of the supported languages included in the `dictionary` scope.
        in: query
        required: true
        type: string
      - name: to
        description: Specifies the language of the output text. The target language must be one of the supported languages included in the `dictionary` scope.
        in: query
        required: true
        type: string
      - name: X-ClientTraceId
        description: A client-generated GUID to uniquely identify the request. Note that you can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId.
        in: header
        required: false
        type: string
      - name: text
        description: "# Request body\nThe body of the request is a JSON array. Each array element is a JSON object with the following properties:\n* `Text-` A string specifying the term to lookup. This should be the value of a `normalizedText` field from the back-translations of a previous Dictionary lookup request. It can also be the value of the `normalizedSource` field.\n* `Translation-` A string specifying the translated text previously returned by the Dictionary lookup operation. This should be the value from the `normalizedTarget` field in the `translations` list of the Dictionary lookup response. The service will return examples for the specific source-target word-pair.\n\nThe following limitations apply:\n* The array can have at most 10 elements.\n* The text value of an array element cannot exceed 100 characters including spaces.\n\n# Response body\nA successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:\n* `normalizedSource-` A string giving the normalized form of the source term. Generally, this should be identical to the value of the `Text` field at the matching list index in the body of the request.\n* `normalizedTarget-` A string giving the normalized form of the target term. Generally, this should be identical to the value of the `Translation` field at the matching list index in the body of the request.\n* `examples-` A list of examples for the (source term, target term) pair. Each element of the list is an object with the following properties:\n  * `sourcePrefix-` The string to concatenate before the value of `sourceTerm` to form a complete example. Do not add a space character, since it is already there when it should be. This value may be an empty string.\n  * `sourceTerm-` A string equal to the actual term looked up. The string is added with `sourcePrefix` and `sourceSuffix` to form the complete example. Its value is separated so it can be marked in a user interface, e.g., by bolding it.\n  * `sourceSuffix-` The string to concatenate after the value of `sourceTerm` to form a complete example. Do not add a space character, since it is already there when it should be. This value may be an empty string.\n  * `targetPrefix-` A string similar to `sourcePrefix` but for the target.\n  * `targetTerm-` A string similar to `sourceTerm` but for the target.\n  * `targetSuffix-` A string similar to `sourceSuffix` but for the target.\n\n# Response Header\nX-RequestId - Value generated by the service to identify the request. It is used for troubleshooting purposes.\nNOTE - If there are no examples in the dictionary, the response is 200 (OK) but the `examples` list is an empty list.\n"
        in: body
        required: true
        schema:
          type: array
          items:
            $ref: '#/definitions/DictionaryExampleTextInput'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/DictionaryExampleResult'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/ErrorMessage'
      x-ms-examples:
        DictionaryExample success example:
          $ref: ./examples/dictionaryExampleSuccess.json
      deprecated: false
      summary: Microsoft Azure Post Dictionary Examples
definitions:
  ErrorMessage:
    type: object
    properties:
      error:
        type: object
        properties:
          code:
            type: string
          message:
            type: string
  DictionaryExampleResult:
    type: array
    description: Example of a successful dictionary example request
    items:
      type: object
      properties:
        normalizedSource:
          type: string
        normalizedTarget:
          type: string
        examples:
          type: array
          items:
            type: object
            properties:
              sourcePrefix:
                type: string
              sourceTerm:
                type: string
              sourceSuffix:
                type: string
              targetPrefix:
                type: string
              targetTerm:
                type: string
              targetSuffix:
                type: string
  DictionaryExampleTextInput:
    type: object
    description: 'Text needed for a dictionary example request '
    properties:
      text:
        type: string
        maximum: 100
      translation:
        type: string
    example:
      text: bug
      translation: bicho
parameters:
  ApiVersion:
    name: api-version
    description: Version of the API requested by the client. Value must be **3.0**.
    in: query
    required: true
    type: string
    default: '3.0'
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'