open-api-spec.yaml

openapi: 3.0.3

info:
  version: 0.0.1
  title: AzNum2Words API
  description: |
    REST API for converting number to words in Azerbaijani language

servers:
  - url: http://localhost:8080

tags:
  - name: Converter
    description: API for converting number to words in Azerbaijani language
  - name: Health
    description: API related to the health of the service

paths:
  /api/v1/conversion/to-word:
    parameters:
      - $ref: '#/components/parameters/x-correlation-id'
    post:
      summary: Convert number to words in Azerbaijani
      description: Convert number to words in Azerbaijani
      operationId: convertNumberToWord
      tags:
        - Converter
      requestBody:
        $ref: '#/components/requestBodies/ConvertNumberToWordsRequest'
      responses:
        200:
          $ref: '#/components/responses/ConvertNumberToWordsResponse'
        default:
          $ref: '#/components/responses/UnknownError'

  /api/v1/conversion/to-number:
    parameters:
      - $ref: '#/components/parameters/x-correlation-id'
    post:
      summary: Convert words in Azerbaijani to number
      description: Convert words in Azerbaijani to number
      operationId: convertWordsToNumber
      tags:
        - Converter
      requestBody:
        $ref: '#/components/requestBodies/ConvertWordsToNumberRequest'
      responses:
        200:
          $ref: '#/components/responses/ConvertWordsToNumberResponse'
        default:
          $ref: '#/components/responses/UnknownError'

  /health:
    get:
      summary: Check the healthapi of the service
      description: Returns a 200 OK response if the service is healthy
      tags:
        - Health
      responses:
        200:
          description: The service is healthy


components:
  schemas:
    Error:
      type: object
      description: Representation of an Error that can appear using the application.
      required:
        - code
        - message
      properties:
        code:
          description: The code of an error that describes the Error.
          type: string
        message:
          description: The message of an error that describes the Error.
          type: string

    ConvertNumberToWords:
      type: object
      description: Convert number to words request representation
      required:
        - number
      properties:
        number:
          description: The number to be converted to words
          type: string

    ConvertWordsToNumber:
      type: object
      description: Convert words to number request representation
      required:
        - words
      properties:
        words:
          description: The words to be converted to number
          type: string

    Word:
      type: object
      description: The number representation in words
      required:
        - words
      properties:
        words:
          description: The number representation in words
          type: string

    Number:
      type: object
      description: Words representation in number
      required:
        - number
      properties:
        number:
          description: Words representation in number
          type: string

  responses:
    UnknownError:
      description: The unknown error appeared. Check your payload or contact support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    ConvertNumberToWordsResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Word'

    ConvertWordsToNumberResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Number'

  requestBodies:
    ConvertNumberToWordsRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ConvertNumberToWords"

    ConvertWordsToNumberRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ConvertWordsToNumber"

  parameters:
    x-correlation-id:
      in: header
      name: x-correlation-id
      required: false
      description: >
        The unique request identifier
      schema:
        type: string