# NOTE: Do not upgrade past Swagger 2. zclient does not support OpenAPI 3 unless
# https://github.com/Yelp/bravado/issues/306 is resolved.
swagger: "2.0"
info:
  description: "A microservice for managing user's trip information"
  version: "1.2.0"
  title: "dispatch_trip"
  contact:
    name: "Infra"
    email: "infrateam@zoox.com"
    url: "https://git.zooxlabs.com/zooxco/driving"
schemes:
  - "http"
  - "https"
basePath: "/v1/"
paths:
  /trips/:
    get:
      summary: "Retrieve the trips"
      operationId: "getTrips"
      produces:
        - "application/json"
      parameters:
        - $ref: "#/parameters/UserId"
        - $ref: "#/parameters/Limit"
        - $ref: "#/parameters/Offset"
      responses:
        "200":
          description: "Operation was successful"
          schema:
            $ref: "#/definitions/TripList"
        "400":
          description: "Invalid parameter was provided"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
    post:
      summary: "Create a trip"
      operationId: "createTrip"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - $ref: "#/parameters/Trip"
      responses:
        "201":
          description: "Operation was successful"
          schema:
            $ref: "#/definitions/Trip"
        "400":
          description: "Invalid trip details was provided"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
  /trips/{trip_id}:
    get:
      summary: "Fetch the trip by its ID"
      operationId: "getTripById"
      produces:
        - "application/json"
      parameters:
        - $ref: "#/parameters/TripId"
      responses:
        "200":
          description: "Operation was successful"
          schema:
            $ref: "#/definitions/Trip"
        "404":
          description: "Trip with the id was not found"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
    put:
      summary: "Update the trip"
      operationId: "updateTrip"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - $ref: "#/parameters/TripId"
        - $ref: "#/parameters/Trip"
      responses:
        "200":
          description: "Operation was successful"
          schema:
            $ref: "#/definitions/Trip"
        "400":
          description: "Invalid Trip details are provided"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "404":
          description: "Trip with the id was not found"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
definitions:
  ErrorInfo:
    type: "object"
    description: "Resource representing the error information"
    properties:
      statusCode:
        type: "integer"
        description: "Error code"
        readOnly: true
      message:
        type: "string"
        description: "Detail info representing the error"
        readOnly: true
    required:
      - statusCode
      - message
  Location:
    type: "object"
    description: "Provides location information"
    properties:
      latitude:
        type: "number"
        format: "double"
        description: "Latitude information for the location"
      longitude:
        type: "number"
        format: "double"
        description: "Longitude information for the location"
      altitudeMeters:
        type: "number"
        format: "double"
        description: "Altitude in meters for the location"
      displayDescription:
        type: "string"
        description: "A text description of this Location. Could be an address, '1149 Chess Dr, Foster\
          \ City, CA` or `Zoox HQ` or `Work`. Fully managed by the client."
    required:
      - latitude
      - longitude
  Trip:
    type: "object"
    description: "Provides the information for a trip"
    properties:
      id:
        type: "string"
        description: "Unique ID to identify the resource"
        readOnly: true
        format: "uuid"
      userId:
        type: "string"
        description: "ID of the user who created the trip"
        readOnly: true
        format: "uuid"
      rideServiceId:
        type: "string"
        description: "Unique ID to identify the ride service that the trip is requested under"
        format: "uuid"
      requestedStartLocation:
        $ref: "#/definitions/Location"
        description: "Actual location where the passenger is requesting the pick up"
      requestedEndLocation:
        $ref: "#/definitions/Location"
        description: "Actual location where the passenger is requesting the drop off"
      requestedMidpoints:
        description: "Points the user would like the robot to drive through when going from Start to End"
        type: "array"
        items:
          $ref: "#/definitions/Location"
      numPublicPassengers:
        type: "integer"
        description: "Number of public passengers (not Zoox-internal)."
      completedTimestamp:
        type: "integer"
        format: "int64"
        description: "Time in epoch seconds at which the trip was completed."
      created:
        type: "integer"
        format: "int64"
        description: "Time in epoch seconds at which the resource has been created"
        readOnly: true
      updated:
        type: "integer"
        format: "int64"
        description: "Time in epoch seconds at which the resource has been last updated"
        readOnly: true
    required:
      - requestedStartLocation
      - requestedEndLocation
      - userId
  ListMetaData:
    type: "object"
    description: "Provides the meta data for various list resources"
    properties:
      limit:
        type: "integer"
        description: "Max number of resources provided in the list"
      offset:
        type: "integer"
        description: "Offset from which the resources are fetched"
      orderBy:
        type: "string"
        description: "Resource's property on which resources are sorted"
      direction:
        type: "string"
        description: "Direction of the sorting order"
        enum:
          - "ASCENDING"
          - "DESCENDING"
      totalCount:
        type: "integer"
        description: "Total number of resources available"
    required:
      - limit
      - offset
      - orderBy
      - direction
      - totalCount
  TripList:
    type: "object"
    description: "Provides a list resource for trips"
    properties:
      metaData:
        $ref: "#/definitions/ListMetaData"
      items:
        type: "array"
        items:
          $ref: "#/definitions/Trip"
    required:
      - metaData
      - items
parameters:
  Limit:
    in: "query"
    name: "limit"
    type: "integer"
    description: "Number of records to limit"
    required: false
    default: 50
    maximum: 100
    minimum: 1
  Offset:
    in: "query"
    name: "offset"
    type: "integer"
    description: "Offset for fetching records in batches. Only returns records higher than offset. Default\
      \ 0 (all)."
    required: false
    default: 0
    minimum: 0
  UserId:
    in: "query"
    name: "user_id"
    type: "string"
    description: "The id of the user who created the trip"
    required: false
  TripId:
    in: "path"
    name: "trip_id"
    description: "Id of the trip"
    type: "string"
    required: true
  Trip:
    in: "body"
    name: "trip"
    schema:
      $ref: "#/definitions/Trip"
    required: true
