openapi: 3.0.1
info:
  title: vehicle-diagnostics api
  description: "Provides APIs for vehicle diagnostics data including maintenance information and vehicle state monitoring."
  version: "2.0"
  contact:
    name: "MAN ServiceCare"
    email: "man_service_care@man.eu"
servers:
  - url: /
tags:
  - name: "Brakes"
    description: "Brake system diagnostics and monitoring"
paths:
  /partners/brakes:
    get:
      tags:
        - "Brakes"
      summary: Get brakes data
      description: Retrieves paginated brakes data for assigned assets
      operationId: getBrakes
      parameters:
        - name: page_size
          in: query
          required: false
          description: Number of items per page
          example: 23
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: page_number
          in: query
          required: false
          description: Page number (zero-based)
          example: 1
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: sort_by
          in: query
          required: false
          description: Field to sort by the response
          schema:
            type: string
            enum:
              - "vehicle"
              - "axlePosition"
              - "left"
              - "right"
            default: "vehicle"
            example: "axlePosition"
        - name: sort_direction
          in: query
          required: false
          schema:
            type: string
            enum:
              - "ASC"
              - "DESC"
            default: "ASC"
        - name: asset_ids
          in: query
          required: false
          description: Used to filter the response to contain only brakes for the specified assets
          example: "47ec272b-d9eb-4ec1-9fe6-e0bc5ae23b80,f41f3f7e-e4f4-47c2-8067-4e2dbeb7668a,be3e639b-465f-49b8-b710-c254c6fbd3e8"
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: min
          in: query
          required: false
          description: Used to filter the response to contain only brakes with pressure values at least at min
          example: 15
          schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 100
        - name: max
          in: query
          required: false
          description: Used to filter the response to contain only brakes with pressure values at most at max
          example: 85
          schema:
            type: integer
            default: 100
            minimum: 0
            maximum: 100
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrakePageResponse'
              example:
                content:
                  - axle_position: "FRONT_AXLE"
                    axle_side: "LEFT"
                    value: 3.1415927
                    status: "NORMAL"
                    resource_id: "23cc75a4-a848-4db1-a322-e0606024b92c"
                    asset:
                      id: "b0dc44c3-a1f4-47fc-ad20-753206ae232b"
                    measured_at:
                      timestamp: "2025-10-28T11:03:56.472842Z"
                      mileage: 9999999.0
                page:
                  page_size: 20
                  page_number: 0
                  total_elements: 1
                  total_pages: 1
        400:
          $ref: '#/components/responses/Problem'
        403:
          $ref: '#/components/responses/Problem'
        404:
          description: No brakes data found
        default:
          $ref: '#/components/responses/Problem'
      security:
        - bearer-auth: []
        - oauth2:
            - vehicle-diagnostics.read
  /partners/assets/{assetId}/brakes:
    parameters:
      - name: assetId
        in: path
        required: true
        schema:
          type: string
          description: assetId of the vehicle
          format: uuid
      - $ref: '#/components/parameters/X-Auth'
    get:
      tags:
        - "Brakes"
      summary: Get brakes data for specific asset
      description: Retrieves brakes data for a specific asset
      operationId: getBrakesForAsset
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Brake'
              example:
                - axle_position: "FRONT_AXLE"
                  axle_side: "LEFT"
                  value: 3.1415927
                  status: "NORMAL"
                  resource_id: "23cc75a4-a848-4db1-a322-e0606024b92c"
                  asset:
                    id: "b0dc44c3-a1f4-47fc-ad20-753206ae232b"
                  measured_at:
                    timestamp: "2025-10-28T11:03:56.472842Z"
                    mileage: 9999999.0
        400:
          $ref: '#/components/responses/Problem'
        403:
          $ref: '#/components/responses/Problem'
        default:
          $ref: '#/components/responses/Problem'
      security:
        - bearer-auth: []
        - oauth2:
            - vehicle-diagnostics.read
components:
  responses:
    Problem:
      description: error occurred - see status code and problem object for more information.
      content:
        'application/problem+json':
          schema:
            $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
  schemas:
    BrakePageResponse:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/Brake'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PageMetadata:
      type: object
      properties:
        page_size:
          type: integer
          format: int32
        page_number:
          type: integer
          format: int32
        total_elements:
          type: integer
          format: int64
        total_pages:
          type: integer
          format: int32
    Brake:
      type: object
      required:
        - asset
        - resource_id
      properties:
        axle_position:
          $ref: '#/components/schemas/AxlePosition'
        axle_side:
          $ref: '#/components/schemas/AxleSide'
        value:
          type: number
          format: float
          example: 3.1415927
        status:
          $ref: '#/components/schemas/Status'
        resource_id:
          type: string
          format: uuid
          example: "23cc75a4-a848-4db1-a322-e0606024b92c"
        asset:
          $ref: '#/components/schemas/Asset'
        measured_at:
          $ref: '#/components/schemas/MeasuredAt'
      example:
        axle_position: "FRONT_AXLE"
        axle_side: "LEFT"
        value: 3.1415927
        status: "NORMAL"
        resource_id: "23cc75a4-a848-4db1-a322-e0606024b92c"
        asset:
          id: "b0dc44c3-a1f4-47fc-ad20-753206ae232b"
        measured_at:
          timestamp: "2025-10-28T11:03:56.472842Z"
          mileage: 9999999.0
    Asset:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          example: "b0dc44c3-a1f4-47fc-ad20-753206ae232b"
    MeasuredAt:
      type: object
      required:
        - timestamp
      properties:
        timestamp:
          type: string
          format: date-time
          example: "2025-10-28T11:03:56.472842Z"
        mileage:
          type: number
          format: double
          example: 9999999.0
    AxlePosition:
      type: string
      enum:
        - FRONT_AXLE
        - REAR_AXLE_1
        - REAR_AXLE_2
        - REAR_AXLE_3
        - REAR_AXLE_4
        - REAR_AXLE_5
        - REAR_AXLE_6
        - REAR_AXLE_7
        - REAR_AXLE_8
        - REAR_AXLE_9
        - REAR_AXLE_10
        - REAR_AXLE_11
        - REAR_AXLE_12
        - RESERVE_WHEELS
    AxleSide:
      type: string
      enum:
        - LEFT
        - RIGHT
    Status:
      type: string
      enum:
        - NORMAL
        - WARNING
        - DANGER
        - UNKNOWN
  securitySchemes:
    bearer-auth:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.iam.rio.cloud/oauth/authorize
          tokenUrl: https://auth.iam.rio.cloud/oauth/token
          scopes:
            vehicle-diagnostics.read: Grants read access
  parameters:
    X-Auth:
      in: header
      name: X-Auth
      description: Token received in case of vin-search
      schema:
        type: string
      required: false
