openapi.yml

openapi: 3.0.0
info:
  title: "Divvun Grammar Checker Server API"
  version: "0.2.0"
  contact:
    name: Brendan Molloy
    email: brendan@technocreatives.com
servers:
  - url: https://api-giellalt.uit.no
    description: Staging server
tags:
  - name: General
  - name: Grammar check
  - name: Spellcheck
  - name: Hyphenation
paths:
  /speller/{languageCode}:
    parameters:
    - name: languageCode
      in: path
      required: true
      example: se
      description: The specified language
      schema:
        type: string
    post:
      operationId: postSpellCheck
      tags: 
        - Spellcheck
      summary: Returns spelling check results
      description: Returns spelling check results for the supplied text and language
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpellCheckRequest"
      responses:
        '200':
          description: List of spelling check results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpellerResponse"
        default:
          description: Error
  /grammar/{languageCode}:
    parameters:
    - name: languageCode
      in: path
      required: true
      example: se
      description: The specified language
      schema:
        type: string
    post:
      operationId: postGrammarCheck
      tags:
        - Grammar check
      summary: Returns grammar check results
      description: Returns grammar check results for the supplied text and language
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GrammarCheckRequest"
      responses:
        '200':
          description: List of grammar check results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GramcheckResponse"
        default:
          description: Error
  /hyphenation/{languageCode}:
    parameters:
    - name: languageCode
      in: path
      required: true
      example: se
      description: The specified language
      schema:
        type: string
    post:
      operationId: postHyphenate
      tags:
        - Hyphenation
      summary: Returns hyphenations for each word in the text
      description: Returns hyphenation results for the supplied text and language
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HyphenationRequest"
      responses:
        '200':
          description: List of hyphenation results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/HyphenationResult"
        default:
          description: Error
  /preferences/grammar/{languageCode}:
    parameters:
    - name: languageCode
      in: path
      required: true
      example: se
      description: The specified language
      schema:
        type: string
    get:
      operationId: getGrammarPreferences
      tags:
        - Grammar check
        - General
      summary: Returns grammar checker preferences
      description: Returns available grammar checker preferences for the specified language code
      responses:
        '200':
          description: A set of preferences
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GramcheckPreferencesResponse"
        default:
          description: Error
  /languages:
    get:
      operationId: getLanguageOptions
      tags:
        - General
      summary: Returns options related to languages
      description: Returns options related to languages, like what languages are available
      responses:
        '200':
          description: A set of options
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AvailableLanguagesResponse"
        default:
          description: Error

components:
  schemas:
    SpellCheckRequest:
      type: object
      required:
        - text
      properties:
        word:
          type: string
    GrammarCheckRequest:
      type: object
      required:
        - text
      properties:
        text:
          type: string
    HyphenationRequest:
      type: object
      required:
        - text
      properties:
        word:
          type: string

    GrammarError:
      type: object
      required:
        - error_text
        - start_index
        - end_index
        - error_code
        - description
        - suggestions
      properties:
        error_text:
          type: string
          example: "servodat dilálašvuođain"
          description: The part of the text which is incorrect
        start_index:
          type: integer
          example: 167
          description: The starting index of the error_text within the submitted text
        end_index:
          type: integer
          example: 190
          description: The ending index of the error_text within the submitted text
        error_code:
          type: string
          example: "msyn-compound"
          description: The identifier of the error
        description:
          type: string
          example: servodat dilálašvuođain berrešii leat oktan sátnin.
          description: The human readable description of what the error is
        suggestions:
          type: array
          description: A list of suggestions for replacing the error_text
          items:
            type: string
            example: servodatdilálašvuođain
            
    GramcheckResponse:
      type: object
      required:
        - text
        - errs
      properties:
        text:
          type: string
          description: The text to which the errors relate to
          example: Bealljeheamit leat, nu movt Norgga Bealljehemiidlihttu oaidná, duvdojuvvon olggobeallai diehtojuohkinservodaga, miidagaha ahte bealljeheamit dávjá ožžot unnit dieđuid servodat dilálašvuođain.
        errs:
          type: array
          items:
            $ref: "#/components/schemas/GrammarError"

    SpellerResult:
      type: object
      required:
        - word
        - isCorrect
        - suggestions
      properties:
        word:
          type: string
          description: the supplied word
          example: oainá
        isCorrect:
          type: boolean
          description: Whether the word is spelled correctly
          example: false
        suggestions:
          type: object
          required:
            - value
            - weight
          properties:
            value:
              type: string
              description: Potential correction
              example: oaidná
            weight:
              type: number
              description: Weight of the correction
              example: 18.432617

    SpellerResponse:
      type: object
      required:
        - text
        - results
      properties:
          text:
            type: string
            description: The supplied text, one or more words
            example: oainá páhkat
          results:
            type: array
            items:
              $ref: "#/components/schemas/SpellerResult"

    GramcheckPreferencesResponse:
      type: object
      properties:
        error_tags:
          type: object
          additionalProperties:
            type: string
          example: { "tag": "description" }

    HyphenationResult:
      type: object
      required:
        - word
        - hyphenations
      properties:
        word:
          type: string
          description: the supplied word
          example: ođasmahtinministtar
        hyphenations:
          type: array
          items:
            type: object
            required:
              - value
              - weight
            properties:
              value:
                type: string
                description: Hyphenation pattern
                example: o^đas^maht^tin#mi^nist^tar
              weight:
                type: string
                description: Weight of the suggestion
                example: 60.000000

    HyphenationResponse:
      type: object
      required:
        - text
        - results
      properties:
        text:
          type: string
          description: The supplied text, one or more words
          example: ođasmahttinministtar ođasmahtinministtar
        results:
          type: array
          items:
            $ref: "#/components/schemas/HyphenationResult"

    AvailableLanguagesResponse:
      type: object
      properties:
        available:
          type: object
          properties:
            grammar:
              type: object
              additionalProperties:
                type: string
              example: { "se": "davvisámegiella", "bg": "български" }
            speller:
              type: object
              additionalProperties:
                type: string
              example: { "se": "davvisámegiella" }
            hyphenation:
              type: object
              additionalProperties:
                type: string
              example: { "se": "davvisámegiella" }