@schmock/openapi 1.1.0

package/src/__fixtures__/train-travel.yaml

@@ -0,0 +1,1264 @@
+openapi: 3.1.0
+info:
+  title: Train Travel API
+  description: |
+    API for finding and booking train trips across Europe.
+
+    ## Run in Postman
+
+    Experiment with this API in Postman, using our Postman Collection.
+
+    [![Run In Postman](https://run.pstmn.io/button.svg =128pxx32px)](https://app.getpostman.com/run-collection/9265903-7a75a0d0-b108-4436-ba54-c6139698dc08?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D9265903-7a75a0d0-b108-4436-ba54-c6139698dc08%26entityType%3Dcollection%26workspaceId%3Df507f69d-9564-419c-89a2-cb8e4c8c7b8f)
+  version: 1.2.1
+  contact:
+    name: Train Support
+    url: https://example.com/support
+    email: support@example.com
+  license:
+    name: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
+    identifier: CC-BY-NC-SA-4.0
+  x-feedbackLink:
+    label: Submit Feedback
+    url: https://github.com/bump-sh-examples/train-travel-api/issues/new
+
+servers:
+  - url: https://try.microcks.io/rest/Train+Travel+API/1.0.0
+    description: Mock Server
+    x-internal: false
+
+  - url: https://api.example.com
+    description: Production
+    x-internal: false
+
+x-speakeasy-retries:
+  strategy: backoff
+  backoff:
+    initialInterval: 500 # 500 milliseconds
+    maxInterval: 60000 # 60 seconds
+    maxElapsedTime: 3600000 # 5 minutes
+    exponent: 1.5
+  statusCodes:
+    - 5XX
+  retryConnectionErrors: true
+  
+security:
+  - OAuth2:
+      - read
+
+x-topics:
+  - title: Getting started
+    content:
+      $ref: ./docs/getting-started.md
+
+tags:
+  - name: Stations
+    description: | 
+      Find and filter train stations across Europe, including their location
+      and local timezone.
+  - name: Trips
+    description: | 
+      Timetables and routes for train trips between stations, including pricing
+      and availability.
+  - name: Bookings
+    description: | 
+      Create and manage bookings for train trips, including passenger details
+      and optional extras.
+  - name: Payments
+    description: |
+      Pay for bookings using a card or bank account, and view payment
+      status and history.
+
+      > warn
+      > Bookings usually expire within 1 hour so you'll need to make your payment
+      > before the expiry date 
+
+paths:
+  /stations:
+    get:
+      summary: Get a list of train stations
+      description: Returns a paginated and searchable list of all train stations.
+      operationId: get-stations
+      tags:
+        - Stations
+      parameters:
+        - $ref: '#/components/parameters/page'
+        - $ref: '#/components/parameters/limit'
+        - name: coordinates
+          in: query
+          description: > 
+            The latitude and longitude of the user's location, to narrow down
+            the search results to sites within a proximity of this location.
+          required: false
+          schema:
+            type: string
+          example: 52.5200,13.4050
+        - name: search
+          in: query
+          description: > 
+            A search term to filter the list of stations by name or address.
+          required: false
+          schema:
+            type: string
+            examples: 
+            - Milano Centrale
+            - Paris
+        - name: country
+          in: query
+          description: Filter stations by country code
+          required: false
+          schema:
+            type: string
+            format: iso-country-code
+          example: DE
+      responses:
+        '200':
+          description: OK
+          headers:
+            Cache-Control:
+              $ref: '#/components/headers/Cache-Control'
+            RateLimit:
+              $ref: '#/components/headers/RateLimit'
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Wrapper-Collection'
+                  - properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/Station'
+                  - properties:
+                      links:
+                        allOf:
+                          - $ref: '#/components/schemas/Links-Self'
+                          - $ref: '#/components/schemas/Links-Pagination'
+              example:
+                data:
+                  - id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                    name: Berlin Hauptbahnhof
+                    address: Invalidenstraße 10557 Berlin, Germany
+                    country_code: DE
+                    timezone: Europe/Berlin
+                  - id: b2e783e1-c824-4d63-b37a-d8d698862f1d
+                    name: Paris Gare du Nord
+                    address: 18 Rue de Dunkerque 75010 Paris, France
+                    country_code: FR
+                    timezone: Europe/Paris
+                links:
+                  self: https://api.example.com/stations&page=2
+                  next: https://api.example.com/stations?page=3
+                  prev: https://api.example.com/stations?page=1
+            application/xml:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Wrapper-Collection'
+                  - properties:
+                      data:
+                        type: array
+                        xml:
+                          name: stations
+                          wrapped: true
+                        items:
+                          $ref: '#/components/schemas/Station'
+                  - properties:
+                      links:
+                        allOf:
+                          - $ref: '#/components/schemas/Links-Self'
+                          - $ref: '#/components/schemas/Links-Pagination'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /trips:
+    get:
+      summary: Get available train trips
+      description: > 
+        Returns a list of available train trips between the specified origin and
+        destination stations on the given date, and allows for filtering by
+        bicycle and dog allowances.
+      operationId: get-trips
+      tags:
+        - Trips
+      parameters:
+        - $ref: '#/components/parameters/page'
+        - $ref: '#/components/parameters/limit'
+        - name: origin
+          in: query
+          description: The ID of the origin station
+          required: true
+          schema:
+            type: string
+            format: uuid
+          example: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+        - name: destination
+          in: query
+          description: The ID of the destination station
+          required: true
+          schema:
+            type: string
+            format: uuid
+          example: b2e783e1-c824-4d63-b37a-d8d698862f1d
+        - name: date
+          in: query
+          description: The date and time of the trip in ISO 8601 format in origin station's timezone.
+          required: true
+          schema:
+            type: string
+            format: date-time
+          example: '2024-02-01T09:00:00Z'
+        - name: bicycles
+          in: query
+          description: Only return trips where bicycles are known to be allowed
+          required: false
+          schema:
+            type: boolean
+            default: false
+        - name: dogs
+          in: query
+          description: Only return trips where dogs are known to be allowed
+          required: false
+          schema:
+            type: boolean
+            default: false
+      responses:
+        '200':
+          description: A list of available train trips
+          headers:
+            Cache-Control:
+              $ref: '#/components/headers/Cache-Control'
+            RateLimit:
+              $ref: '#/components/headers/RateLimit'
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Wrapper-Collection'
+                  - properties:
+                      data:
+                        type: array
+                        items:
+                          allOf:
+                            - $ref: '#/components/schemas/Trip'
+                            - $ref: '#/components/schemas/Links-Origin'
+                            - $ref: '#/components/schemas/Links-Destination'
+                  - properties:
+                      links:
+                        allOf:
+                          - $ref: '#/components/schemas/Links-Self'
+                          - $ref: '#/components/schemas/Links-Pagination'
+              example:
+                data:
+                  - id: ea399ba1-6d95-433f-92d1-83f67b775594
+                    origin: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                    destination: b2e783e1-c824-4d63-b37a-d8d698862f1d
+                    departure_time: '2024-02-01T10:00:00Z'
+                    arrival_time: '2024-02-01T16:00:00Z'
+                    price: 50
+                    operator: Deutsche Bahn
+                    bicycles_allowed: true
+                    dogs_allowed: true
+                    links:
+                      self: https://api.example.com/trips/ea399ba1-6d95-433f-92d1-83f67b775594
+                      origin: https://api.example.com/stations/efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                      destination: https://api.example.com/stations/b2e783e1-c824-4d63-b37a-d8d698862f1d
+                  - id: 4d67459c-af07-40bb-bb12-178dbb88e09f
+                    origin: b2e783e1-c824-4d63-b37a-d8d698862f1d
+                    destination: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                    departure_time: '2024-02-01T12:00:00Z'
+                    arrival_time: '2024-02-01T18:00:00Z'
+                    price: 50
+                    operator: SNCF
+                    bicycles_allowed: true
+                    dogs_allowed: true
+                    links:
+                      self: https://api.example.com/trips/4d67459c-af07-40bb-bb12-178dbb88e09f
+                      origin: https://api.example.com/stations/b2e783e1-c824-4d63-b37a-d8d698862f1d
+                      destination: https://api.example.com/stations/efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                links:
+                  self: https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01
+                  next: https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=b2e783e1-c824-4d63-b37a-d8d698862f1d&date=2024-02-01&page=2
+            application/xml:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Wrapper-Collection'
+                  - properties:
+                      data:
+                        type: array
+                        xml:
+                          name: trips
+                          wrapped: true
+                        items:
+                          $ref: '#/components/schemas/Trip'
+                  - properties:
+                      links:
+                        allOf:
+                          - $ref: '#/components/schemas/Links-Self'
+                          - $ref: '#/components/schemas/Links-Pagination'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  /bookings:
+    get:
+      operationId: get-bookings
+      summary: List existing bookings
+      description: Returns a list of all trip bookings by the authenticated user.
+      tags:
+        - Bookings
+      parameters:
+        - $ref: '#/components/parameters/page'
+        - $ref: '#/components/parameters/limit'
+      responses:
+        '200':
+          description: A list of bookings
+          headers:
+            Cache-Control:
+              $ref: '#/components/headers/Cache-Control'
+            RateLimit:
+              $ref: '#/components/headers/RateLimit'
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Wrapper-Collection'
+                  - properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/Booking'
+                  - properties:
+                      links:
+                        allOf:
+                          - $ref: '#/components/schemas/Links-Self'
+                          - $ref: '#/components/schemas/Links-Pagination'
+              example:
+                data:
+                  - id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                    trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                    passenger_name: John Doe
+                    has_bicycle: true
+                    has_dog: true
+                  - id: b2e783e1-c824-4d63-b37a-d8d698862f1d
+                    trip_id: b2e783e1-c824-4d63-b37a-d8d698862f1d
+                    passenger_name: Jane Smith
+                    has_bicycle: false
+                    has_dog: false
+                links:
+                  self: https://api.example.com/bookings
+                  next: https://api.example.com/bookings?page=2
+            application/xml:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Wrapper-Collection'
+                  - properties:
+                      data:
+                        type: array
+                        xml:
+                          name: bookings
+                          wrapped: true
+                        items:
+                          $ref: '#/components/schemas/Booking'
+                  - properties:
+                      links:
+                        allOf:
+                          - $ref: '#/components/schemas/Links-Self'
+                          - $ref: '#/components/schemas/Links-Pagination'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    post:
+      operationId: create-booking
+      summary: Create a booking
+      description: A booking is a temporary hold on a trip. It is not confirmed until the payment is processed.
+      tags:
+        - Bookings
+      security:
+        - OAuth2:
+            - write
+      requestBody:
+        description: Booking details
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Booking'
+          application/xml:
+            schema:
+              $ref: '#/components/schemas/Booking'
+      responses:
+        '201':
+          description: Booking successful
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Booking'
+                  - properties:
+                      links:
+                        $ref: '#/components/schemas/Links-Self'
+
+              example:
+                id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                passenger_name: John Doe
+                has_bicycle: true
+                has_dog: true
+                links:
+                  self: https://api.example.com/bookings/efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+            application/xml:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Booking'
+                  - properties:
+                      links:
+                        $ref: '#/components/schemas/Links-Self'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+  
+  /bookings/{bookingId}:
+    parameters:
+      - name: bookingId
+        in: path
+        required: true
+        description: The ID of the booking to retrieve.
+        schema:
+          type: string
+          format: uuid
+        example: 1725ff48-ab45-4bb5-9d02-88745177dedb
+    get:
+      summary: Get a booking
+      description: Returns the details of a specific booking.
+      operationId: get-booking
+      tags:
+        - Bookings
+      responses:
+        '200':
+          description: The booking details
+          headers:
+            Cache-Control:
+              $ref: '#/components/headers/Cache-Control'
+            RateLimit:
+              $ref: '#/components/headers/RateLimit'
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Booking'
+                  - properties:
+                      links:
+                        $ref: '#/components/schemas/Links-Self'
+              example:
+                id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+                passenger_name: John Doe
+                has_bicycle: true
+                has_dog: true
+                links:
+                  self: https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb
+            application/xml:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Booking'
+                  - properties:
+                      links:
+                        $ref: '#/components/schemas/Links-Self'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+    delete:
+      summary: Delete a booking
+      description: Deletes a booking, cancelling the hold on the trip.
+      operationId: delete-booking
+      security:
+        - OAuth2:
+            - write
+      tags:
+        - Bookings
+      responses:
+        '204':
+          description: Booking deleted
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /bookings/{bookingId}/payment:
+    parameters:
+      - name: bookingId
+        in: path
+        required: true
+        description: The ID of the booking to pay for.
+        schema:
+          type: string
+          format: uuid
+        example: 1725ff48-ab45-4bb5-9d02-88745177dedb
+    post:
+      summary: Pay for a Booking
+      description: A payment is an attempt to pay for the booking, which will confirm the booking for the user and enable them to get their tickets.
+      operationId: create-booking-payment
+      tags:
+        - Payments
+      requestBody:
+        description: Payment details
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BookingPayment'
+            examples:
+              Card:
+                summary: Card Payment
+                value:
+                  amount: 49.99
+                  currency: gbp
+                  source:
+                    object: card
+                    name: J. Doe
+                    number: '4242424242424242'
+                    cvc: '123'
+                    exp_month: 12
+                    exp_year: 2025
+                    address_line1: 123 Fake Street
+                    address_line2: 4th Floor
+                    address_city: London
+                    address_country: gb
+                    address_post_code: N12 9XX
+              Bank:
+                summary: Bank Account Payment
+                value:
+                  amount: 100.5
+                  currency: gbp
+                  source:
+                    object: bank_account
+                    name: J. Doe
+                    number: '00012345'
+                    sort_code: '000123'
+                    account_type: individual
+                    bank_name: Starling Bank
+                    country: gb
+      responses:
+        '200':
+          description: Payment successful
+          headers:
+            Cache-Control:
+              $ref: '#/components/headers/Cache-Control'
+            RateLimit:
+              $ref: '#/components/headers/RateLimit'
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/BookingPayment'
+                  - properties:
+                      links:
+                        $ref: '#/components/schemas/Links-Booking'
+              examples:
+                Card:
+                  summary: Card Payment
+                  value:
+                    id: 2e3b4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a
+                    amount: 49.99
+                    currency: gbp
+                    source:
+                      object: card
+                      name: J. Doe
+                      number: '************4242'
+                      cvc: '123'
+                      exp_month: 12
+                      exp_year: 2025
+                      address_country: gb
+                      address_post_code: N12 9XX
+                    status: succeeded
+                    links:
+                      booking: https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb/payment
+                Bank:
+                  summary: Bank Account Payment
+                  value:
+                    id: 2e3b4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a
+                    amount: 100.5
+                    currency: gbp
+                    source:
+                      object: bank_account
+                      name: J. Doe
+                      account_type: individual
+                      number: '*********2345'
+                      sort_code: '000123'
+                      bank_name: Starling Bank
+                      country: gb
+                    status: succeeded
+                    links:
+                      booking: https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+webhooks:
+  newBooking:
+    post:
+      operationId: new-booking
+      summary: New Booking
+      description: |
+        Subscribe to new bookings being created, to update integrations for your users.  Related data is available via the links provided in the request.
+      tags:
+        - Bookings
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              allOf: 
+                - $ref: '#/components/schemas/Booking'
+                - properties:
+                    links:
+                      allOf:
+                        - $ref: '#/components/schemas/Links-Self'
+                        - $ref: '#/components/schemas/Links-Pagination'
+            example:
+              id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+              trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+              passenger_name: John Doe
+              has_bicycle: true
+              has_dog: true
+              links:
+                self: https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb
+      responses:
+        '200':
+          description: Return a 200 status to indicate that the data was received successfully.
+
+components:
+  parameters:
+    page: 
+      name: page
+      in: query
+      description: The page number to return
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        default: 1
+      example: 1
+
+    limit:
+      name: limit
+      in: query
+      description: The number of items to return per page
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 10
+      example: 10
+
+  securitySchemes:
+    OAuth2:
+      type: oauth2
+      description: OAuth 2.0 authorization code following RFC8725 best practices.
+      flows:
+        authorizationCode:
+          authorizationUrl: https://example.com/oauth/authorize
+          tokenUrl: https://example.com/oauth/token
+          scopes:
+            read: Read access
+            write: Write access
+  schemas:
+    Station:
+      description: A train station.
+      type: object
+      xml:
+        name: station
+      required:
+        - id
+        - name
+        - address
+        - country_code
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique identifier for the station.
+          examples:
+            - efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+            - b2e783e1-c824-4d63-b37a-d8d698862f1d
+        name:
+          type: string
+          description: The name of the station
+          examples:
+            - Berlin Hauptbahnhof
+            - Paris Gare du Nord
+        address:
+          type: string
+          description: The address of the station.
+          examples:
+            - Invalidenstraße 10557 Berlin, Germany
+            - 18 Rue de Dunkerque 75010 Paris, France
+        country_code:
+          type: string
+          description: The country code of the station.
+          format: iso-country-code
+          examples:
+            - DE
+            - FR
+        timezone:
+          type: string
+          description: The timezone of the station in the [IANA Time Zone Database format](https://www.iana.org/time-zones).
+          examples:
+            - Europe/Berlin
+            - Europe/Paris
+    Links-Self:
+      description: The link to the current resource.
+      type: object
+      properties:
+        self:
+          type: string
+          format: uri
+    Links-Destination:
+      description: The link to the destination station resource.
+      type: object
+      properties:
+        self:
+          type: string
+          format: uri
+    Links-Origin:
+      description: The link to the origin station resource.
+      type: object
+      properties:
+        self:
+          type: string
+          format: uri
+    Links-Pagination:
+      description: Links to the next and previous pages of a paginated response.
+      type: object
+      properties:
+        next:
+          type: string
+          format: uri
+        prev:
+          type: string
+          format: uri
+    Problem:
+      description: A problem detail object as defined in RFC 7807.
+      type: object
+      xml:
+        name: problem
+        namespace: urn:ietf:rfc:7807
+      properties:
+        type:
+          type: string
+          description: A URI reference that identifies the problem type
+          examples: 
+          - https://example.com/probs/out-of-credit
+        title:
+          type: string
+          description: A short, human-readable summary of the problem type
+          examples: 
+          - You do not have enough credit.
+        detail:
+          type: string
+          description: A human-readable explanation specific to this occurrence of the problem
+          examples: 
+          - Your current balance is 30, but that costs 50.
+        instance:
+          type: string
+          description: A URI reference that identifies the specific occurrence of the problem
+          examples: 
+          - /account/12345/msgs/abc
+        status:
+          type: integer
+          description: The HTTP status code
+          examples: 
+          - 400
+    Trip:
+      description: A train trip.
+      type: object
+      xml:
+        name: trip
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique identifier for the trip
+          examples:
+            - 4f4e4e1-c824-4d63-b37a-d8d698862f1d
+        origin:
+          type: string
+          description: The starting station of the trip
+          examples:
+            - efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+            - b2e783e1-c824-4d63-b37a-d8d698862f1d
+        destination:
+          type: string
+          description: The destination station of the trip
+          examples:
+            - b2e783e1-c824-4d63-b37a-d8d698862f1d
+            - efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
+        departure_time:
+          type: string
+          format: date-time
+          description: The date and time when the trip departs
+          examples:
+            - '2024-02-01T10:00:00Z'
+        arrival_time:
+          type: string
+          format: date-time
+          description: The date and time when the trip arrives
+          examples:
+            - '2024-02-01T16:00:00Z'
+        operator:
+          type: string
+          description: The name of the operator of the trip
+          examples:
+            - Deutsche Bahn
+            - SNCF
+        price:
+          type: number
+          description: The cost of the trip
+          examples:
+            - 50
+        bicycles_allowed:
+          type: boolean
+          description: Indicates whether bicycles are allowed on the trip
+        dogs_allowed:
+          type: boolean
+          description: Indicates whether dogs are allowed on the trip
+    Booking:
+      description: A booking for a train trip.
+      type: object
+      xml:
+        name: booking
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique identifier for the booking
+          readOnly: true
+          examples:
+            - 3f3e3e1-c824-4d63-b37a-d8d698862f1d
+        trip_id:
+          type: string
+          format: uuid
+          description: Identifier of the booked trip
+          examples:
+            - 4f4e4e1-c824-4d63-b37a-d8d698862f1d
+        passenger_name:
+          type: string
+          description: Name of the passenger
+          examples:
+            - John Doe
+        has_bicycle:
+          type: boolean
+          description: Indicates whether the passenger has a bicycle.
+        has_dog:
+          type: boolean
+          description: Indicates whether the passenger has a dog.
+    Wrapper-Collection:
+      description: This is a generic request/response wrapper which contains both data and links which serve as hypermedia controls (HATEOAS).
+      type: object
+      properties:
+        data:
+          description: The wrapper for a collection is an array of objects.
+          type: array
+          items:
+            type: object
+        links:
+          description: A set of hypermedia links which serve as controls for the client.
+          type: object
+          readOnly: true
+      xml:
+        name: data
+    BookingPayment:
+      description: A payment for a booking.
+      type: object
+      properties:
+        id:
+          description: Unique identifier for the payment. This will be a unique identifier for the payment, and is used to reference the payment in other objects.
+          type: string
+          format: uuid
+          readOnly: true
+        amount:
+          description: Amount intended to be collected by this payment. A positive decimal figure describing the amount to be collected.
+          type: number
+          exclusiveMinimum: 0
+          examples:
+            - 49.99
+        currency:
+          description: Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
+          type: string
+          enum:
+            - bam
+            - bgn
+            - chf
+            - eur
+            - gbp
+            - nok
+            - sek
+            - try
+        source:
+          unevaluatedProperties: false
+          description: The payment source to take the payment from. This can be a card or a bank account. Some of these properties will be hidden on read to protect PII leaking.
+          oneOf:
+            - title: Card
+              description: A card (debit or credit) to take payment from.
+              type: object
+              properties:
+                object:
+                  type: string
+                  const: card
+                name:
+                  type: string
+                  description: Cardholder's full name as it appears on the card.
+                  examples:
+                    - Francis Bourgeois
+                number:
+                  type: string
+                  description: The card number, as a string without any separators. On read all but the last four digits will be masked for security.
+                  examples:
+                    - '4242424242424242'
+                cvc:
+                  type: string
+                  description: Card security code, 3 or 4 digits usually found on the back of the card.
+                  minLength: 3
+                  maxLength: 4
+                  writeOnly: true
+
+                  example: '123'
+                exp_month:
+                  type: integer
+                  format: int64
+                  description: Two-digit number representing the card's expiration month.
+                  examples:
+                    - 12
+                exp_year:
+                  type: integer
+                  format: int64
+                  description: Four-digit number representing the card's expiration year.
+                  examples:
+                    - 2025
+                address_line1:
+                  type: string
+                  writeOnly: true
+                address_line2:
+                  type: string
+                  writeOnly: true
+                address_city:
+                  type: string
+                address_country:
+                  type: string
+                address_post_code:
+                  type: string
+              required:
+                - name
+                - number
+                - cvc
+                - exp_month
+                - exp_year
+                - address_country
+            - title: Bank Account
+              description: A bank account to take payment from. Must be able to make payments in the currency specified in the payment.
+              type: object
+              properties:
+                object:
+                  const: bank_account
+                  type: string
+                name:
+                  type: string
+                number:
+                  type: string
+                  description: The account number for the bank account, in string form. Must be a current account.
+                sort_code:
+                  type: string
+                  description: The sort code for the bank account, in string form. Must be a six-digit number.
+                account_type:
+                  enum:
+                    - individual
+                    - company
+                  type: string
+                  description: The type of entity that holds the account. This can be either `individual` or `company`.
+                bank_name:
+                  type: string
+                  description: The name of the bank associated with the routing number.
+                  examples:
+                    - Starling Bank
+                country:
+                  type: string
+                  description: Two-letter country code (ISO 3166-1 alpha-2).
+              required:
+                - name
+                - number
+                - account_type
+                - bank_name
+                - country
+        status:
+          description: The status of the payment, one of `pending`, `succeeded`, or `failed`.
+          type: string
+          enum:
+            - pending
+            - succeeded
+            - failed
+          readOnly: true
+    Links-Booking:
+      description: The link to the booking resource.
+      type: object
+      properties:
+        booking:
+          type: string
+          format: uri
+          examples:
+            - https://api.example.com/bookings/1725ff48-ab45-4bb5-9d02-88745177dedb
+  headers:
+    Cache-Control:
+      description: |
+        The Cache-Control header communicates directives for caching mechanisms in both requests and responses. 
+        It is used to specify the caching directives in responses to prevent caches from storing sensitive information.
+      schema:
+        type: string
+        description: A comma-separated list of directives as defined in [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html).
+        examples:
+          - max-age=3600
+          - max-age=604800, public
+          - no-store
+          - no-cache
+          - private
+      
+    RateLimit:
+      description: |
+        The RateLimit header communicates quota policies. It contains a `limit` to
+        convey the expiring limit, `remaining` to convey the remaining quota units,
+        and `reset` to convey the time window reset time.
+      schema:
+        type: string
+        examples:
+          - limit=10, remaining=0, reset=10
+
+    Retry-After:
+      description: | 
+        The Retry-After header indicates how long the user agent should wait before making a follow-up request. 
+        The value is in seconds and can be an integer or a date in the future. 
+        If the value is an integer, it indicates the number of seconds to wait. 
+        If the value is a date, it indicates the time at which the user agent should make a follow-up request. 
+      schema:
+        type: string
+      examples:
+        integer:
+          value: '120'
+          summary: Retry after 120 seconds
+        date:
+          value: 'Fri, 31 Dec 2021 23:59:59 GMT'
+          summary: Retry after the specified date
+  responses:
+    BadRequest:
+      description: Bad Request
+      headers:
+        RateLimit:
+          $ref: '#/components/headers/RateLimit'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/bad-request
+            title: Bad Request
+            status: 400
+            detail: The request is invalid or missing required parameters.
+        application/problem+xml:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/bad-request
+            title: Bad Request
+            status: 400
+            detail: The request is invalid or missing required parameters.
+
+    Conflict:
+      description: Conflict
+      headers:
+        RateLimit:
+          $ref: '#/components/headers/RateLimit'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/conflict
+            title: Conflict
+            status: 409
+            detail: There is a conflict with an existing resource.
+        application/problem+xml:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/conflict
+            title: Conflict
+            status: 409
+            detail: There is a conflict with an existing resource.
+
+    Forbidden:
+      description: Forbidden
+      headers:
+        RateLimit:
+          $ref: '#/components/headers/RateLimit'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/forbidden
+            title: Forbidden
+            status: 403
+            detail: Access is forbidden with the provided credentials.
+        application/problem+xml:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/forbidden
+            title: Forbidden
+            status: 403
+            detail: Access is forbidden with the provided credentials.
+
+    InternalServerError:
+      description: Internal Server Error
+      headers:
+        RateLimit:
+          $ref: '#/components/headers/RateLimit'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/internal-server-error
+            title: Internal Server Error
+            status: 500
+            detail: An unexpected error occurred.
+        application/problem+xml:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/internal-server-error
+            title: Internal Server Error
+            status: 500
+            detail: An unexpected error occurred.
+
+    NotFound:
+      description: Not Found
+      headers:
+        RateLimit:
+          $ref: '#/components/headers/RateLimit'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/not-found
+            title: Not Found
+            status: 404
+            detail: The requested resource was not found.
+        application/problem+xml:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/not-found
+            title: Not Found
+            status: 404
+            detail: The requested resource was not found.
+
+    TooManyRequests:
+      description: Too Many Requests
+      headers:
+        RateLimit:
+          $ref: '#/components/headers/RateLimit'
+        Retry-After:
+          $ref: '#/components/headers/Retry-After'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/too-many-requests
+            title: Too Many Requests
+            status: 429
+            detail: You have exceeded the rate limit.
+        application/problem+xml:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/too-many-requests
+            title: Too Many Requests
+            status: 429
+            detail: You have exceeded the rate limit.
+
+    Unauthorized:
+      description: Unauthorized
+      headers:
+        RateLimit:
+          $ref: '#/components/headers/RateLimit'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/unauthorized
+            title: Unauthorized
+            status: 401
+            detail: You do not have the necessary permissions.
+        application/problem+xml:
+          schema:
+            $ref: '#/components/schemas/Problem'
+          example:
+            type: https://example.com/errors/unauthorized
+            title: Unauthorized
+            status: 401
+            detail: You do not have the necessary permissions.