Update Train Travel API and add mock server

hubs/my-train-company/trainbook-openapi-source.yaml

@@ -14,10 +14,18 @@ info:
   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://api.example.com
     description: Production
+    x-internal: false
+
+  - url: https://try.microcks.io/rest/Train+Travel+API/1.0.0
+    description: Mock Server
+    x-internal: false
 
 security:
   - OAuth2:
@@ -54,14 +62,46 @@ paths:
   /stations:
     get:
       summary: Get a list of train stations
-      description: Returns a list of all train stations in the system.
+      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: A list of train stations
+          description: OK
           headers:
+            Cache-Control:
+              $ref: '#/components/headers/Cache-Control'
             RateLimit:
               $ref: '#/components/headers/RateLimit'
           content:
@@ -125,11 +165,16 @@ paths:
   /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.
+      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
@@ -157,7 +202,7 @@ paths:
         - name: bicycles
           in: query
           description: Only return trips where bicycles are known to be allowed
-          required: true
+          required: false
           schema:
             type: boolean
             default: false
@@ -172,6 +217,8 @@ paths:
         '200':
           description: A list of available train trips
           headers:
+            Cache-Control:
+              $ref: '#/components/headers/Cache-Control'
             RateLimit:
               $ref: '#/components/headers/RateLimit'
           content:
@@ -246,10 +293,15 @@ paths:
       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:
@@ -309,6 +361,7 @@ paths:
           $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalServerError'
+
     post:
       operationId: create-booking
       summary: Create a booking
@@ -387,6 +440,8 @@ paths:
         '200':
           description: The booking details
           headers:
+            Cache-Control:
+              $ref: '#/components/headers/Cache-Control'
             RateLimit:
               $ref: '#/components/headers/RateLimit'
           content:
@@ -466,6 +521,7 @@ paths:
       tags:
         - Payments
       requestBody:
+        required: true
         content:
           application/json:
             schema:
@@ -505,6 +561,8 @@ paths:
         '200':
           description: Payment successful
           headers:
+            Cache-Control:
+              $ref: '#/components/headers/Cache-Control'
             RateLimit:
               $ref: '#/components/headers/RateLimit'
           content:
@@ -594,6 +652,30 @@ webhooks:
           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
@@ -664,30 +746,36 @@ components:
           type: string
           format: uri
     Problem:
+      type: object
       xml:
         name: problem
         namespace: urn:ietf:rfc:7807
       properties:
         type:
           type: string
           description: A URI reference that identifies the problem type
-          example: https://example.com/probs/out-of-credit
+          examples: 
+          - https://example.com/probs/out-of-credit
         title:
           type: string
           description: A short, human-readable summary of the problem type
-          example: You do not have enough credit.
+          examples: 
+          - You do not have enough credit.
         detail:
           type: string
           description: A human-readable explanation specific to this occurrence of the problem
-          example: Your current balance is 30, but that costs 50.
+          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
-          example: /account/12345/msgs/abc
+          examples: 
+          - /account/12345/msgs/abc
         status:
           type: integer
           description: The HTTP status code
-          example: 400
+          examples: 
+          - 400
     Trip:
       type: object
       xml:
@@ -813,9 +901,10 @@ components:
         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.
-          anyOf:
+          oneOf:
             - title: Card
               description: A card (debit or credit) to take payment from.
+              type: object
               properties:
                 object:
                   type: string
@@ -921,6 +1010,20 @@ components:
           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
@@ -946,7 +1049,6 @@ components:
         date:
           value: 'Fri, 31 Dec 2021 23:59:59 GMT'
           summary: Retry after the specified date
-
   responses:
     BadRequest:
       description: Bad Request