Train Info API

openapi: 3.0.0
info:
  title: Train & Station Information API
  version: 1.0.0
  description: API for managing and retrieving information about trains and stations.
servers:
  - url: https://api.traininfo.com/v1
    description: Production server
  - url: http://localhost:8080/v1
    description: Local development server

tags:
  - name: Trains
    description: Operations related to individual train services.
  - name: Stations
    description: Operations related to train stations.

paths:
  /trains:
    get:
      summary: Get all trains
      tags:
        - Trains
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: Filter trains by name.
        - in: query
          name: type
          schema:
            type: string
            enum: [express, local, intercity]
          description: Filter trains by type.
      responses:
        '200':
          description: A list of trains.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Train'
        '500':
          $ref: '#/components/responses/ErrorResponse'
    post:
      summary: Create a new train
      tags:
        - Trains
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrainCreate'
      responses:
        '201':
          description: Train created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Train'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /trains/{trainId}:
    get:
      summary: Get a train by ID
      tags:
        - Trains
      parameters:
        - in: path
          name: trainId
          schema:
            type: string
            format: uuid
          required: true
          description: ID of the train to retrieve.
      responses:
        '200':
          description: Train details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Train'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ErrorResponse'
    put:
      summary: Update an existing train
      tags:
        - Trains
      parameters:
        - in: path
          name: trainId
          schema:
            type: string
            format: uuid
          required: true
          description: ID of the train to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrainUpdate'
      responses:
        '200':
          description: Train updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Train'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      summary: Delete a train
      tags:
        - Trains
      parameters:
        - in: path
          name: trainId
          schema:
            type: string
            format: uuid
          required: true
          description: ID of the train to delete.
      responses:
        '204':
          description: Train deleted successfully.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /stations:
    get:
      summary: Get all stations
      tags:
        - Stations
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: Filter stations by name.
        - in: query
          name: city
          schema:
            type: string
          description: Filter stations by city.
      responses:
        '200':
          description: A list of stations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
        '500':
          $ref: '#/components/responses/ErrorResponse'
    post:
      summary: Create a new station
      tags:
        - Stations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StationCreate'
      responses:
        '201':
          description: Station created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Station'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ErrorResponse'

  /stations/{stationId}:
    get:
      summary: Get a station by ID
      tags:
        - Stations
      parameters:
        - in: path
          name: stationId
          schema:
            type: string
            format: uuid
          required: true
          description: ID of the station to retrieve.
      responses:
        '200':
          description: Station details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Station'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ErrorResponse'
    put:
      summary: Update an existing station
      tags:
        - Stations
      parameters:
        - in: path
          name: stationId
          schema:
            type: string
            format: uuid
          required: true
          description: ID of the station to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StationUpdate'
      responses:
        '200':
          description: Station updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Station'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ErrorResponse'
    delete:
      summary: Delete a station
      tags:
        - Stations
      parameters:
        - in: path
          name: stationId
          schema:
            type: string
            format: uuid
          required: true
          description: ID of the station to delete.
      responses:
        '204':
          description: Station deleted successfully.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ErrorResponse'

components:
  schemas:
    Train:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the train.
        trainNumber:
          type: string
          description: Unique identifier number for the train.
          example: "12001"
        name:
          type: string
          description: Name of the train.
          example: "Express to Galle"
        type:
          type: string
          enum: [express, local, intercity, long_distance]
          description: Type of the train service.
          example: "express"
        capacity:
          type: integer
          format: int32
          description: Total passenger capacity of the train.
          example: 800
      required:
        - trainNumber
        - name
        - type
        - capacity
    TrainCreate:
      type: object
      properties:
        trainNumber:
          type: string
          description: Unique identifier number for the train.
          example: "12001"
        name:
          type: string
          description: Name of the train.
          example: "Express to Galle"
        type:
          type: string
          enum: [express, local, intercity, long_distance]
          description: Type of the train service.
          example: "express"
        capacity:
          type: integer
          format: int32
          description: Total passenger capacity of the train.
          example: 800
      required:
        - trainNumber
        - name
        - type
        - capacity
    TrainUpdate:
      type: object
      properties:
        name:
          type: string
          description: Name of the train.
          example: "Galle Intercity Express"
        type:
          type: string
          enum: [express, local, intercity, long_distance]
          description: Type of the train service.
          example: "intercity"
        capacity:
          type: integer
          format: int32
          description: Total passenger capacity of the train.
          example: 850

    Station:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the station.
        name:
          type: string
          description: Name of the station.
          example: "Colombo Fort"
        code:
          type: string
          description: Unique short code for the station.
          example: "CMB"
        city:
          type: string
          description: City where the station is located.
          example: "Colombo"
        latitude:
          type: number
          format: float
          description: Latitude coordinate of the station.
          example: 6.932
        longitude:
          type: number
          format: float
          description: Longitude coordinate of the station.
          example: 79.846
      required:
        - name
        - code
        - city
    StationCreate:
      type: object
      properties:
        name:
          type: string
          description: Name of the station.
          example: "Kandy"
        code:
          type: string
          description: Unique short code for the station.
          example: "KND"
        city:
          type: string
          description: City where the station is located.
          example: "Kandy"
        latitude:
          type: number
          format: float
          description: Latitude coordinate of the station.
          example: 7.291
        longitude:
          type: number
          format: float
          description: Longitude coordinate of the station.
          example: 80.634
      required:
        - name
        - code
        - city
    StationUpdate:
      type: object
      properties:
        name:
          type: string
          description: Name of the station.
          example: "Kandy Central"
        city:
          type: string
          description: City where the station is located.
          example: "Kandy"
        latitude:
          type: number
          format: float
          description: Latitude coordinate of the station.
          example: 7.291
        longitude:
          type: number
          format: float
          description: Longitude coordinate of the station.
          example: 80.634

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: "RESOURCE_NOT_FOUND"
        message:
          type: string
          example: "The requested resource was not found."

  responses:
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ResourceNotFound:
              value:
                code: "RESOURCE_NOT_FOUND"
                message: "The requested resource was not found."
    BadRequest:
      description: Invalid request payload or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            InvalidInput:
              value:
                code: "INVALID_INPUT"
                message: "One or more required fields are missing or invalid."
    ErrorResponse:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            InternalServerError:
              value:
                code: "INTERNAL_SERVER_ERROR"
                message: "An unexpected error occurred on the server."