openapi: '3.0.1'
info:
  title: Usage Transparency API
  description: |
    This API also allows platform and third party applications to record application usages by users/assets/tenants for billing, reporting, quota checking purposes.
    
    While adding the usages
    - UTS accepts all the data that is sent, provided it is in valid format and payload does not exceed the limit of usages count per request.
    - In case rules are configured for the usage units, the corresponding usage data is verified against the rule.
    - If verification fails, the data will be rejected and is not aggregated.
    - If /usagesJobs endpoint was used for sending the data, caller can query for the status of the data.
    - A rule is necessary in case the usages are to be billed.
    
    ## Limitations
    
    - The number of usages that can be added to UTS in a single request is limited to 200, regardless of whether usages are for single or multiple users.
    - Tenants can query the status of up to 1000 recent jobs that they created to add the usages to UTS.
    - The amount of operations performed that can be performed are limited per time, and may be throttled.
    
    ## Terms
    - Rule - Rules are created in UTS to define which valid data will be accepted as usage.
    - KPI - KPI are created in UTS to defined how the accepted usage data will be aggregated and made available for consumer.
    
    ### Generic Errors
    
    The following generic error codes might occur at any of the specified operations. Generic errors are prefixed with 'mdsp.core.generic.'.

    - 204: noContent
    - 400: invalidParameter
    - 400: invalidRequestBodyProperty
    - 400: missingParameter
    - 400: missingRequestBodyProperty
    - 401: unauthorized
    - 403: forbidden
    - 404: noMatch
    - 413: payloadTooLarge
    - 415: unsupportedMediaType
    - 429: tooManyRequests
    - 500: internalServerError

  version: 3.3.0
  x-visibility: external

servers:
  - url: https://api.eu1.siemens.app/usagetransparency-1000001700/v3
    description: Xcelerator compliant URL

tags:
  - name: usage
    description: Send application specific usages to UTS backend.
  - name: usage-jobs-with-traceability
    description: Jobs API to provide traceability and add usages for multiple tenants and users.
  - name: aggregated-monthly-usage
    description: Get monthly aggregated usages for consumer and provider tenants.

## ************************************************************************* ##
## ************************** API Methods ********************************** ##
## ************************************************************************* ##

paths:
  ############################################
  ## Add usages for single tenant and user. ##
  ############################################
  /usages:
    post:
      security:
        - uts:
            - uts.su
      tags:
        - usage
      summary: Send application specific usages to UTS backend.
      description: >-
        This method can be used by operators and applications to send application
        specific usages (e.g. number of created report pages, CPU times per user, 
        assets configured, etc.) to the UTS.<br>
        Use this endpoint to send <b>USAGES of a SINGLE TENANT and USER</b> to UTS.<br>
        Caller can use the GET /usagesJobs API to get the status of the sent data.
      requestBody:
        description: 'send object contains the usages.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUsage'
      responses:
        '200':
          description: Data is successfully saved to the database
        '400':
          description: |
            Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorSchema'
            text/plain:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorisedErrorSchema'
            text/plain:
              schema:
                type: string
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorSchema'
            text/plain:
              schema:
                type: string

  ####################################################################################
  ## Jobs API to provide traceability and add usages for multiple tenants and user. ##
  ####################################################################################
  /usagesJobs:
    ## Add usages ##
    post:
      security:
        - uts:
            - uts.su
      tags:
        - usage-jobs-with-traceability
      summary: Add usages for one or more tenants, users and applications to UTS for storage and processing.
      description: |
        This method can be used by operators and applications to create a job that adds application specific usages (e.g. number of created report pages, CPU times per user, assets configured, etc.) to the UTS.
        - Maximum of 200 usages can be added by one job. Larger payloads are immediately and completely rejected.
        - Use this endpoint to add <b> USAGES of MULTIPLE TENANTS and USERS</b> to UTS.
        - The returned <b>id</b> can be used later to query the status of the UTS process for the job and added usages.
        - In case the usages need to be billed, a rule must be created in UTS.
        
        In case the <b>userId</b> is not provided in the payload, the <b>tenantId</b> is used as <b>userId</b>, also <b>userType</b> is then <b>tenant</b>.
      requestBody:
        description: List object of customer and user specific usages
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Users'
      responses:
        '202':
          description: 'ACCEPTED'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsagesJob'
        '400':
          description: 'Provided request body is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPErrors'
        '413':
          description: 'Request payload is too large'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPErrors'

    ## Status of jobs ##
    get:
      security:
        - uts:
            - uts.su
            - uts.tu
      tags:
        - usage-jobs-with-traceability
      summary: Query status of processing for the jobs that added the usages.
      description: |
        Returns overall summary of the jobs and optionally the usages added using /usages APIs.
        - Callers are not usually expected to use this API as part of business workflow, but for '<i>in-frequent auditing</i>'.
        - <b>The calls to this method may be throttled</b>.
        - Only 1000 latest jobs per operator tenant can be retrieved.
        - Description of job statuses.
          - ACCEPTED: A job is created, and the usages have been accepted.
          - INPROGRESS: Processing is on-going on at least one of the usages added by the job.
          - ERRORS: There is at least one error encountered while processing the usages.
          - COMPLETED: All the processes applicable to the usages have been completed.
      parameters:
        - in: query
          name: date
          required: false
          schema:
            type: string
          description: 'Date on which usages had been added in yyyy-mm-dd format. default value is current date.'
        - in: query
          name: tenant
          required: false
          schema:
            type: string
          description: 'Tenant for which usage had been added'
        - in: query
          name: application
          required: false
          schema:
            type: string
          description: 'Application for which usage had been added'
        - in: query
          name: unit
          required: false
          schema:
            type: string
          description: 'Resource usage unit'
        - name: page
          in: query
          description: Page Number
          required: false
          schema:
            type: integer
            default: 1
            maximum: 20
        - name: size
          in: query
          description: Page Size
          required: false
          schema:
            type: integer
            default: 10
            maximum: 100
      responses:
        '200':
          description: 'Job summaries retrieved'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsagesJobQueryResult'

  /usagesJobs/{id}:
    ## Status of usages added by a job ##
    get:
      security:
        - uts:
            - uts.su
            - uts.tu
      tags:
        - usage-jobs-with-traceability
      summary: Retrieve the status of processing of usages that were added by the job.
      description: |
        Returns status summary of the usages added by the data sent using /usages APIs.
        - Callers are not usually expected to use this API as part of business workflow, but for '<i>in-frequent auditing</i>'.
        - <b>The calls to this method may be throttled.</b>
        - Description of usage statuses.
          - ACCEPTED: Usages have been accepted.
          - VERIFIED: Usages have been verified against the rules configured in rule engine, if applicable.
          - VERIFICATIONFAILED: Verification of at least one of the usages has failed.
          - NOVERIFICATION: No applicable rule was found and hence no verification was done.
          - AGGREGATED: Usages have been aggregated into a running daily aggregate value based on the aggregation function defined in UTS rule. In case no rule is applicable, default aggregation function 'SUM' is used. The aggregation is performed every hour and the daily aggregate is updated. Once aggregated, the UTS can be queried to report the usages through UI or data endpoints.
          - SENTFORBILLING: If billing is enabled for the usages, the data has been sent successfully to the billing system.
          - FAILEDTOSENDFORBILLING: Errors were encountered while sending the data to billing. These could be network issues or other internal errors.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: 'id of the job that was used to send the usages.'
        - name: page
          in: query
          description: 'page number'
          required: false
          schema:
            type: integer
            default: 1
            maximum: 10
        - name: size
          in: query
          description: 'page size'
          required: false
          schema:
            type: integer
            default: 200
      responses:
        '200':
          description: 'usages summary for the job retrieved.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsagesJobSummary'

  /usagesJobs/{id}/errors:
    ## Errors encountered in processing usages ##
    get:
      security:
        - uts:
            - uts.su
            - uts.tu
      tags:
        - usage-jobs-with-traceability
      summary: Retrieve the processing errors related the usages added by the job.
      description: |
        Returns the errors, if any, associated with a set of usages that were received by the identified job.
        - Callers are not usually expected to use this API as part of business workflow, but for '<i>in-frequent auditing</i>'.
        - <b>The calls to this method may be throttled.</b>
        - In case of 'Verification Errors', the list of usages that failed verification is part of the errors.
        - In case of 'Billing Errors', billing ids are part of the error data. API users need to contact UTS team with the billing-ids to resolve the issues.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: 'id of the job that was used to send the usages.'
        - in: query
          name: errorClass
          required: false
          schema:
            type: string
          description: Error Class - validation|billing|errors
        - name: page
          in: query
          description: Page Number
          required: false
          schema:
            type: integer
            default: 1
        - name: size
          in: query
          description: Page Size
          required: false
          schema:
            type: integer
            default: 10
            maximum: 100
      responses:
        '200':
          description: 'Usage errors retrieved.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageErrors'

  ############################################
  ## Get usage as a consumer tenant.        ##
  ############################################
  /aggregatedMonthlyConsumerUsage:
    get:
      security:
        - uts:
            - uts.r
      tags:
        - aggregated-monthly-usage
      summary: Get monthly aggregated usages of rule enabled for consumer tenant.
      description: |
        
        Operator registers a KPI with UTS. Operator send the resource usage data of consumer to UTS. 
        KPI contains the aggregation and unit conversion details which should be applied on received usages.
        
        Aggregation is executed and calculated values are shown in response. This API endpoint can be used by consumer tenant to see the aggregated usage calculated for month on prorate basis.
      parameters:
        - name: month
          in: query
          description: Month for which usage requested
          required: true
          schema:
            type: string
            enum:
              - January
              - February
              - March
              - April
              - May
              - June
              - July
              - August
              - September
              - October
              - November
              - December
        - name: year
          in: query
          description: Year
          required: true
          schema:
            type: string
        - name: provider
          in: query
          description: Provider tenant Id
          required: true
          schema:
            type: string
        - name: application
          in: query
          description: Application name registered on gateway
          required: true
          schema:
            type: string
        - name: KPIName
          in: query
          description: Name of the KPI registered with UTS for application
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/aggregatedTenantUsageData'
        '400':
          description: 'BAD REQUEST'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPErrorsV3'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPErrorsV3'

  /aggregatedMonthlyProviderUsage:
    get:
      security:
        - uts:
            - uts.r
      tags:
        - aggregated-monthly-usage
      summary: Get monthly aggregated usages for rule enabled to consumer tenants.
      description: |
        
        Operator registers a KPI with UTS. Operator send the resource usage data of consumer to UTS. 
        KPI contains the aggregation and unit conversion details which should be applied on received usages.
        
        Aggregation is executed and calculated values are shown in response. This API endpoint can be used by provider tenant to see the aggregated usage calculated for month on prorate basis for various consumers.
      parameters:
        - name: month
          in: query
          description: Month for which usage requested
          required: true
          schema:
            type: string
            enum:
              - January
              - February
              - March
              - April
              - May
              - June
              - July
              - August
              - September
              - October
              - November
              - December
        - name: year
          in: query
          description: year
          required: true
          schema:
            type: string
        - name: consumer
          in: query
          description: Consumer tenant id
          schema:
            type: string
        - name: application
          in: query
          description: Application name registered on gateway
          required: true
          schema:
            type: string
        - name: KPIName
          in: query
          description: Name of the KPI registered with UTS for application
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/size'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/aggregatedMonthyOperatorUsages'
        '400':
          description: 'BAD REQUEST'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPErrorsV3'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPErrorsV3'

## ************************************************************************* ##
## ************************** Model Definitions *************************** ##
## ************************************************************************* ##

components:

  schemas:

    ################################
    ## To Be Deprecated UTS Model ##
    ################################

    UserUsage:
      type: object
      required:
        - CustomerTenantID
        - CustomerUserID
        - UTSUsageData
      properties:
        CustomerTenantID:
          type: string
          example: test
        CustomerUserID:
          type: string
          example: test@gmail.com
        UTSUsageData:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationUsage'

    ApplicationUsage:
      type: object
      properties:
        resourceAlias:
          type: string
          example: 'assetmonitor'
          description: 'An  application that consumes or manipulates a resource and provides some service. an application is the main actor that generates usages'
        resourceName:
          type: string
          example: 'assetid1'
          description: |
            A resource for which the usage is being reported by the application (resourceAlias), e.g asset, user, app, action, url, operation.
            If user want to send multiple keywords as a value for resourceName then hyphen (-) should be used to separate the keywords.
        UsageData:
          type: array
          items:
            $ref: '#/components/schemas/ResourceUsage'

    ResourceUsage:
      type: object
      properties:
        usage:
          type: integer
          example: 20
        usageUnit:
          type: string
          example: 'asset-count'
          description: 'Represents an action performed by the application, e.g. sending sms, onboarding of asset, etc.'
        usageDate:
          type: string
          example: '2011-07-14T19:43:37+0100'

    ##############################
    ## Models tenant usage data ##
    ##############################
    aggregatedTenantUsageData:
      type: object
      properties:
        provider:
          type: string
          example: provider
          description: The tenant id which owns the application
        application:
          type: string
          example: assetmonitor
          description: The application name registered on gateway
        applicationDisplayName:
          type: string
          example: Asset Monitor
          description: The application display name
        KPIName:
          type: string
          example: asset-count
          description: Rule name registered with UTS
        KPIDisplayName:
          type: string
          example: asset count
          description: The display name of rule which is known to consumer
        aggregationUntilDate:
          type: string
          example: '2011-07-14'
          description: 'Date until received data is aggregated in UTC timezone.'
        year:
          type: string
          example: '2021'
          description: Year for which the usages are requested
        month:
          type: string
          example: 'january'
          description: Month for which the usages are requested
        aggragationFunction:
          $ref: '#/components/schemas/aggregationFunction'
      allOf:
        - $ref: '#/components/schemas/aggregatedUsageData'

    aggregationFunction:
      type: object
      properties:
        aggregationFunctionDaily:
          type: string
          description: These are UTS supported aggregation functions for day.
          enum:
            - MIN
            - MAX
            - AVERAGE
            - SUM
            - COUNT
            - LAST
            - FIRST
          example: SUM
        aggregationFunctionMonthly:
          type: string
          description: These are UTS supported aggregation functions for month.
          enum:
            - MIN
            - MAX
            - AVERAGE
            - SUM
            - COUNT
            - LAST
            - FIRST
            - AVERAGE_DAYS_IN_MONTH
          example: SUM
        preFill:
          type: string
          description: The aggregate function computes the billing unit for the day. The preFill option provides you a way to configure the behaviour when no data is received for a defined rule then should UTS consider it as empty , zero or it should use the value from previous day.
          enum:
            - ZERO
            - EMPTY
            - PREVIOUS
          example: ZERO

    aggregatedUsageData:
      type: object
      required:
        - consumer
        - value
      properties:
        consumer:
          type: string
          example: bmw
          description: The tenant id which has used provider application
        value:
          type: integer
          example: 20
          description: 'Represents the amount of units consumed.'

    ############################
    ## Models for usage details#
    ############################
    aggregatedMonthyOperatorUsages:
      type: object
      properties:
        provider:
          type: string
          example: provider
          description: The operator which owns the application
        application:
          type: string
          example: assetmonitor
          description: The application name registered on gateway
        applicationDisplayName:
          type: string
          example: Asset Monitor
          description: The application display name
        KPIName:
          type: string
          example: asset-count
          description: Rule name registered with UTS
        KPIDisplayName:
          type: string
          example: asset count
          description: The display name of rule which is known to consumer
        aggregationUntilDate:
          type: string
          example: '2011-07-14'
          description: 'Date until received data is aggregated in UTC timezone.'
        year:
          type: string
          example: '2021'
          description: Year for which the usages are requested
        month:
          type: string
          example: 'january'
          description: Month for which the usages are requested
        aggregatedUsages:
          type: array
          items:
            $ref: '#/components/schemas/aggregatedUsageData'
        aggragationFunction:
          $ref: '#/components/schemas/aggregationFunction'
        page:
          $ref: '#/components/schemas/Page'

    BadRequestErrorSchema:
      $ref: '#/components/schemas/HTTPErrorsWithStatus'

    ForbiddenErrorSchema:
      $ref: '#/components/schemas/HTTPErrorsWithStatus'

    UnauthorisedErrorSchema:
      $ref: '#/components/schemas/HTTPErrorsWithStatus'

    HTTPErrorsWithStatus:
      type: object
      properties:
        code:
          type: string
          description: 'UTS specific error code'
          example: 'UTS-Exxx|mdsp.<provider>.<service/app>.<errorid>'
        message:
          type: string
          description: 'Error message in English'
          example: '<error message in english>'
        logref:
          type: string
          description: 'log correlation-id'
          example: '0bff7e7a-cd25-4576-9908-4180ef086174'
        status:
          type: integer
          example: 403

    #######################
    ## UTS Usages Models ##
    #######################
    Users:
      type: object
      required:
        - users
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'

    User:
      type: object
      required:
        - tenantId
        - resources
      properties:
        tenantId:
          type: string
          example: test
        userId:
          type: string
          example: test@gmail.com
        userType:
          type: string
          enum:
            - tenant
            - user
            - agent
          example: user
          default: tenant
          description: "Type of user i.e. interactive user, an agent or usage corresponds to entire tenant. if not specified, default is 'user'"
        resources:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationResource'

    ApplicationResource:
      type: object
      required:
        - application
        - resource
        - usages
      properties:
        application:
          type: string
          example: 'assetmonitor'
          description: 'An application that consumes or manipulates a resource and provides some service. an application is the main actor that generates usages. the name should be same as the registered application name. in case no application is specified, alias name will be considered as the application name.'
        alias:
          type: string
          example: 'analyze-my-performance'
          description: 'An application may realize multiple business cases, in such a case aliases can be used to distinguish between the business cases realized by same application. alias should be named so that it conveys the underlying business case. in case no alias is provided, application name will be considered as the alias.'
        resource:
          type: string
          example: 'assetid1'
          description: |
            A resource for which the usage is being reported by the application (resourceAlias), e.g asset, user, app, action, url, operation.
            If user want to send multiple keyword as a value for resourceName then hyphen (-) should be used to Separate the keywords.
        usages:
          type: array
          items:
            $ref: '#/components/schemas/Usage'

    Usage:
      type: object
      required:
        - value
        - unit
        - datetime
      properties:
        value:
          type: integer
          example: 20
          description: 'Represents the amount of units consumed.'
        unit:
          type: string
          example: 'asset-count'
          description: 'Represents a trackable or billable action performed by the application, e.g. sending SMS, onboarding of asset, etc.'
        datetime:
          type: string
          example: '2011-07-14T19:43:37Z'
          description: 'Time at which the usage occurred, in UTC clock time.'
        tags:
          type: array
          description: The maximum allowed tags are 10
          items:
            $ref: '#/components/schemas/tag'
          minItems: 0
          maxItems: 10

    tag:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          example: assetid
          minLength: 1
          maxLength: 40
          description: Key of the tag
        value:
          type: string
          example: d032adb5-a6e1-4a14-a07a-ab47df7caf13
          minLength: 1
          maxLength: 40
          description: Value of the tag

    #############################################
    ## Models for Reporting UTS Process Status ##
    #############################################
    UsagesJob:
      type: object
      properties:
        id:
          type: string
          example: '35a4cb01-2497-4191-ad1c-551a1942c409-20190520131'
          description: 'The id recevied in response to /usagesJobs endpoint'
        time:
          type: string
          example: '2011-07-14T19:43:37Z'
        status:
          type: string
          description: 'The status is based on the status of the usages that satisfy the query.'
          enum:
            - ACCEPTED
            - INPROGRESS
            - ERRORS
            - COMPLETED
        usagesCount:
          type: integer
          description: 'Number of usages that satisfy the query and identified by the id.'
          example: 7

    UsagesSummary:
      type: object
      properties:
        application:
          type: string
          example: 'assetmonitor'
        unit:
          type: string
          example: 'asset-count'
        usagesCount:
          type: integer
          description: 'Number of usages that satisfy the query within the application, unit, and job id.'
          example: 2
        processStatus:
          type: string
          enum:
            - ACCEPTED
            - VERIFIED
            - VERIFICATIONFAILED
            - NOVERIFICATION
            - AGGREGATED
            - SENTFORBILLING
            - FAILEDTOSENDFORBILLING
            - RECEIVEDFORBILLING

    UsagesJobSummary:
      allOf:
        - $ref: '#/components/schemas/UsagesJob'
        - type: object
          properties:
            usagesSummary:
              type: array
              items:
                $ref: '#/components/schemas/UsagesSummary'
            page:
              $ref: '#/components/schemas/Page'

    UsagesJobQueryResult:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/UsagesJob'
        page:
          $ref: '#/components/schemas/Page'

    ########################
    ## Common Error Model ##
    ########################
    Error:
      type: object
      properties:
        code:
          type: string
          description: ' mdsp.<provider>.<service/app>.<errorid>'
          example: 'mdsp.<provider>.<service/app>.<errorid>'
        message:
          type: string
          description: 'Error message in english'
          example: '<error message in english>'
        messageParameters:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: name1
              value:
                type: string
                example: value1
        logref:
          type: string
          description: 'Log correlation-id'
          example: '0bff7e7a-cd25-4576-9908-4180ef086174'

    ############################
    ## Models for HTTP Errors ##
    ############################
    HTTPErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'

    #####################################
    ## Error models for UTS processing ##
    #####################################
    UsageError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            errorType:
              type: string
              enum:
                - ValidationError
                - BillingError
                - OtherError
            info:
              type: string
              description: 'Reference to more information if available'
              example: 'http://developer.mindsphere.io/uts/documentation/billing'
      discriminator:
        propertyName: errorType

    ############################
    ## MDSP  Errors Schema    ##
    ############################
    HTTPErrorsV3:
      type: object
      properties:
        errors:
          type: array
          description: Array of errors.
          items:
            type: object
            properties:
              code:
                type: string
                description: UTS error code as per MDSP standard.
                example: 'mdsp.core.uts.<see response description>'
              message:
                type: string
                description: Detailed description of error.
                example: '<see response description>'
              logref:
                type: string
                description: Log reference id.
                example: '737b7f76-50aa-4169-bd74-6c8a0edbe922'

    UsageErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/UsageError'
        page:
          $ref: '#/components/schemas/Page'

    #################################
    ## Common Model for Pagination ##
    #################################
    Page:
      type: object
      properties:
        number:
          type: integer
          example: 2
        size:
          type: integer
          example: 10
        totalElements:
          type: integer
          example: 40
        totalPages:
          type: integer
          example: 4
      title: PageDetails

  parameters:
    page:
      name: page
      in: query
      schema:
        type: integer
        default: 0
      description: Specifies the requested page index.
    size:
      name: size
      in: query
      schema:
        type: integer
        default: 20
      description: Specifies the number of elements in a page

  securitySchemes:
    uts:
      type: oauth2
      description: |
        For **Xcelerator** compliance, please use **authorizationUrl** = https://1000001700.eu1.sws.siemens.com/oauth/authorize and **tokenUrl** = https://1000001700.eu1.sws.siemens.com/oauth/token
      flows:
        authorizationCode:
          authorizationUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/authorize'
          tokenUrl: 'https://1000001700.eu1.sws.siemens.com/oauth/token'
          scopes:
            uts.su: Grants access to (s)end (u)sage information
            uts.tu: Grant access to (t)rack the processing of (u)sages
            uts.r: Grants access to request for usages
