openapi.yaml

            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /api/cities/{cityId}/airports/{airportId}:
    post:
      tags:
        - City
      summary: Assign airport to a city.
      operationId: assignAirport
      parameters:
        - name: cityId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: airportId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CityDto'
        "400":
          description: Input data not correct
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    put:
      tags:
        - City
      summary: Update assignment of airport to a city.
      operationId: updateAirportAssignment
      parameters:
        - name: cityId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: airportId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CityDto'
        "400":
          description: Input data not correct
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    delete:
      tags:
        - City
      summary: Delete assignment of airport to a city.
      operationId: deleteAirportAssignment
      parameters:
        - name: cityId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: airportId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Deleted
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /api/airports:
    get:
      tags:
        - Airport
      summary: Get all airports.
      description: Returns an array of objects representing airports.
      operationId: getAllAirports
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AirportDto'
    post:
      tags:
        - Airport
      summary: Create a new airport.
      description: Creates a new airport and returns it as a response.
      operationId: createAirport
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewAirportDtoRequest'
        required: true
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportDto'
        "400":
          description: Input data not correct
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /api/airports/{id}:
    get:
      tags:
        - Airport
      summary: Get airport by id.
      description: Returns an object representing an airport.
      operationId: getAirportById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportDto'
    delete:
      tags:
        - Airport
      summary: Delete airport by id.
      operationId: deleteAirport
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Deleted
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    put:
      tags:
        - Airport
      summary: Update city by id.
      operationId: updateAirport
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      description: Updates a airport by id and returns it as a response.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AirportDto'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportDto'
        "400":
          description: Input data not correct
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /api/airports/{airportId}/departingFlights/{departingFlightId}:
    post:
      tags:
        - Airport
      summary: Assign departing flight to an airport.
      operationId: assignDepartingFlight
      parameters:
        - name: airportId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: departingFlightId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportDto'
        "400":
          description: Input data not correct
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    put:
      tags:
        - Airport
      summary: Update assignment of departing flight to an airport.
      operationId: updateDepartingFlightAssignment
      parameters:
        - name: airportId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: departingFlightId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportDto'
        "400":
          description: Input data not correct
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    delete:
      tags:
        - Airport
      summary: Delete assignment of departing flight to an airport.
      operationId: deleteDepartingFlightAssignment
      parameters:
        - name: airportId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: departingFlightId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Deleted
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
  /api/airports/{airportId}/arrivingFlights/{arrivingFlightId}:
    post:
      tags:
        - Airport
      summary: Assign arriving flight to an airport.
      operationId: assignArrivingFlight
      parameters:
        - name: airportId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: arrivingFlightId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportDto'
        "400":
          description: Input data not correct
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    put:
      tags:
        - Airport
      summary: Update assignment of arriving flight to an airport.
      operationId: updateArrivingFlightAssignment
      parameters:
        - name: airportId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: arrivingFlightId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirportDto'
        "400":
          description: Input data not correct
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    delete:
      tags:
        - Airport
      summary: Delete assignment of arriving flight to an airport.
      operationId: deleteArrivingFlightAssignment
      parameters:
        - name: airportId
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: arrivingFlightId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Deleted
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    DomainEntityDto:
      title: Domain Entity
      description: Represents a Domain Entity
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          description: unique id
          format: int64
          example: 1
      discriminator:
        propertyName: objectType
    ErrorMessage:
      title: Error Message
      description: Response body for HTML statuses.
      type: object
      properties:
        timestamp:
          type: string
          description: time in ISO format
          format: date-time
          example: 2022-12-21T18:52:10.757Z
        status:
          type: integer
          description: HTTP status code
          format: int32
          example: 404
        error:
          type: string
          description: HTTP status text
          example: Not Found
        message:
          type: string
          description: reason for error
          example: entity not found
        path:
          type: string
          description: URL path
          example: /api/stewards/1
    StewardDto:
      allOf:
        - $ref: '#/components/schemas/DomainEntityDto'
      type: object
      title: Steward
      description: Represents a steward on a flight.
      required:
        - id
        - firstName
        - lastName
      properties:
        firstName:
          type: string
          description: first name of a steward
          example: John
        lastName:
          type: string
          description: last name of a steward
          example: Doe
        flights:
          type: array
          description: flights assigned to a steward
          items:
            $ref: '#/components/schemas/FlightDto'
    NewStewardDtoRequest:
      type: object
      title: New Steward Request
      description: Object for requesting a new Steward.
      required:
        - firstName
        - lastName
      properties:
        firstName:
          type: string
          description: first name of a steward
          example: John
        lastName:
          type: string
          description: last name of a steward
          example: Doe
    FlightDto:
      allOf:
        - $ref: '#/components/schemas/DomainEntityDto'
      type: object
      title: Flight
      description: Represents a flight.
      required:
        - id
        - departureTime
        - arrivalTime
        - stewards
        - airplane
        - departureAirport
        - arrivalAirport
      properties:
        departureTime:
          type: string
          description: time of flight departure
          format: date-time
          example: 2022-12-22T12:04:04.493908908+01:00
        arrivalTime:
          type: string
          description: time of flight arrival
          format: date-time
          example: 2022-12-22T12:04:04.493908908+01:00
        stewards:
          type: array
          description: stewards assigned to a flight
          items:
            $ref: '#/components/schemas/StewardDto'
        airplane:
          $ref: '#/components/schemas/AirplaneDto'
        departureAirport:
          $ref: '#/components/schemas/AirportDto'
        arrivalAirport:
          $ref: '#/components/schemas/AirportDto'
    NewFlightDtoRequest:
      type: object
      title: New Flight Request
      description: Object for requesting a new Flight.
      required:
        - departureTime
        - arrivalTime
      properties:
        departureTime:
          type: string
          description: time of flight departure
          format: date-time
          example: 2022-12-22T12:04:04.493908908+01:00
        arrivalTime:
          type: string
          description: time of flight arrival
          format: date-time
          example: 2022-12-22T12:04:04.493908908+01:00
    AirplaneTypeDto:
      allOf:
        - $ref: '#/components/schemas/DomainEntityDto'
      type: object
      title: Airplane Type
      description: Represents an Airplane Type.
      required:
        - id
        - name
      properties:
        name:
          type: string
          description: airplane type name
          example: Boeing 747
    NewAirplaneTypeDtoRequest:
      type: object
      title: New Airplane Type Request
      description: Object for requesting a new Airplane Type.
      required:
        - name
      properties:
        name:
          type: string
          description: airplane type name
          example: Boeing 747
    AirplaneDto:
      allOf:
        - $ref: '#/components/schemas/DomainEntityDto'
      type: object
      title: Airplane
      description: Represents an Airplane.
      required:
        - id
        - name
        - capacity
        - type
      properties:
        name:
          type: string
          description: airplane name
          example: Spitfire
        capacity:
          type: integer
          description: airplane seat capacity
          format: int32
          example: 150
        type:
          $ref: '#/components/schemas/AirplaneTypeDto'
    NewAirplaneDtoRequest:
      type: object
      title: New Airplane Request
      description: Object for requesting a new Airplane.
      required:
        - name
        - capacity
      properties:
        name:
          type: string
          description: airplane name
          example: Spitfire
        capacity:
          type: integer
          description: airplane seat capacity
          format: int32
          example: 150
    PageableObject:
      type: object
      title: Pageable Object
      properties:
        offset:
          type: integer
          format: int64
        sort:
          $ref: '#/components/schemas/SortObject'
        pageSize:
          type: integer
          format: int32
        pageNumber:
          type: integer
          format: int32
        paged:
          type: boolean
        unpaged:
          type: boolean
    SortObject:
      type: object
      title: Sort Object
      properties:
        empty:
          type: boolean
        sorted:
          type: boolean
        unsorted:
          type: boolean
    PageStewardDto:
      type: object
      title: Paged Stewards
      properties:
        totalPages:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
        first:
          type: boolean
        last:
          type: boolean
        size:
          type: integer
          format: int32
        content:
          type: array
          items:
            $ref: '#/components/schemas/StewardDto'
        number:
          type: integer
          format: int32
        sort:
          $ref: '#/components/schemas/SortObject'
        numberOfElements:
          type: integer
          format: int32
        pageable:
          $ref: '#/components/schemas/PageableObject'
        empty:
          type: boolean
    CountryDto:
      allOf:
        - $ref: '#/components/schemas/DomainEntityDto'
      type: object
      title: Country
      description: Represents a country.
      required:
        - id
        - name
      properties:
        name:
          type: string
          description: country name
          example: Canada
    NewCountryDtoRequest:
      type: object
      title: New Country Request
      description: Object for requesting a new Country.
      required:
        - name
      properties:
        name:
          type: string
          description: country name
          example: Canada
    CityDto:
      allOf:
        - $ref: '#/components/schemas/DomainEntityDto'
      type: object
      title: City
      description: Represents a City in a Country containing Airports.
      required:
        - id
        - name
      properties:
        name:
          type: string
          description: city name
          example: London
        country:
          $ref: '#/components/schemas/CountryDto'
        airports:
          type: array
          items:
            $ref: '#/components/schemas/AirportDto'
    NewCityDtoRequest:
      type: object
      title: New City Request
      description: Object for requesting a new City.
      required:
        - name
      properties:
        name:
          type: string
          description: city name
          example: London
    GPSLocationDto:
      type: object
      title: GPS Location
      description: Represents a GPS Location of latitude and longitude.
      required:
        - latitude
        - longitude
      properties:
        latitude:
          type: number
          format: double
          example: 41.40338
        longitude:
          type: number
          format: double
          example: 2.17403
    AirportDto:
      allOf:
        - $ref: '#/components/schemas/DomainEntityDto'
      type: object
      title: Airport
      description: Represents an Airport.
      required:
        - id
        - name
        - code
        - departingFlights
        - arrivingFlights
        - city
        - location
      properties:
        name:
          type: string
          description: airport name
          example: John F. Kennedy International Airport
        code:
          type: string
          description: airport code in IATA format
          example: JFK
        departingFlights:
          type: array
          items:
            $ref: '#/components/schemas/FlightDto'
        arrivingFlights:
          type: array
          items:
            $ref: '#/components/schemas/FlightDto'
        city:
          $ref: '#/components/schemas/CityDto'
        location:
          $ref: '#/components/schemas/GPSLocationDto'
    NewAirportDtoRequest:
      type: object
      title: New Airport Type Request
      description: Object for requesting a new Airport.
      required:
        - name
        - code
        - cityId
        - location
      properties:
        name:
          type: string
          description: airport name
          example: John F. Kennedy International Airport
        code:
          type: string
          description: airport code in IATA format
          example: JFK
        cityId:
          type: integer
          format: int64
        location:
          $ref: '#/components/schemas/GPSLocationDto'
  responses:
    SingleStewardDtoResponse:
      description: Response containing a single Steward.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StewardDto'
      links:
        link_to_getSteward:
          operationId: getSteward
          parameters:
            id: $response.body#/id
          description: |
            The `id` value returned in the response can be used as
            the `id` parameter in `GET /stewards/{id}`.