docs: revise OAS (#479)

Co-authored-by: Sarah Mischinger <[email protected]>
Co-authored-by: Martin Kolárik <[email protected]>

public/v1/components/examples.yaml

@@ -27,6 +27,9 @@ components:
         ]
     createMeasurementPingLocations:
       summary: 'ping: specific locations'
+      description: |
+        Use the `locations` object to define locations from which the API should select probes.
+        In this example, we're selecting probes based on the `country`, but you can use other properties like `city`, `asn`, etc. to fine-tune the selection.
       value:
         {
           "type": "ping",
@@ -38,6 +41,10 @@ components:
         }
     createMeasurementPingLocationsLimit:
       summary: 'ping: specific locations and limit'
+      description: |
+        Use the `limit` property to specify how many probes the API should pick per location.
+        Alternatively, you can use the measurement's global `limit` property to have the API divide the probes evenly among the locations.
+        If you don't define a limit value, the global limit value is set to 1.
       value:
         {
           "type": "ping",
@@ -49,6 +56,12 @@ components:
         }
     createMeasurementPingLocationsMagic:
       summary: 'ping: magic location filter'
+      description: |
+        Instead of defining the individual object properties for each location type, you can ask the API to find the best match across
+        all location fields. For example, rather than explicitly defining a country and a city, you can write `magic: country+city`.
+
+        We recommend using this field in real time applications that allow free-form user input. On the other hand, defining the
+        specific location keys may be a better option for scripts, as it makes the selection stricter and therefore more predictable.
       value:
         {
           "type": "ping",
@@ -67,6 +80,7 @@ components:
         }
     createMeasurementPingCustom:
       summary: 'ping: custom options'
+      description: Depending on the measurement `type`, you may provide additional measurement options. In this example, we set the number of packets to send for our ping test. You can find all available options in the request body schema.
       value:
         {
           "type": "ping",
@@ -77,6 +91,7 @@ components:
         }
     createMeasurementPingLocationsMeasurementId:
       summary: 'ping: previous measurement id'
+      description: If you want to reuse probes from a previous measurement, pass its `id` in the `locations` field. Note that some probes may be offline and no longer unavailable - this will be indicated in the results.
       value:
         {
           "type": "ping",

public/v1/components/headers.yaml

@@ -32,7 +32,7 @@ components:
       schema:
         type: integer
     RateLimitReset:
-      description: The number of seconds until the limit is reset.
+      description: The number of seconds until the limit resets.
       required: true
       schema:
         type: integer

public/v1/components/parameters.yaml

@@ -1,6 +1,7 @@
 components:
   parameters:
     measurementId:
+      description: The ID of the measurement you want to retrieve.
       in: path
       name: id
       required: true

public/v1/components/responses.yaml

@@ -1,7 +1,9 @@
 components:
   responses:
     '400':
-      description: Bad Request
+      description: |
+        If the API couldn't process the request due to malformed parameters or other client errors, it returns status `400 Bad Request`
+        and a body with more information about the error. Please modify your request before trying again.
       content:
         application/json:
           schema:
@@ -11,16 +13,20 @@ components:
             properties:
               error:
                 type: object
+                description: Information about the error.
                 required:
                   - type
                   - message
                 properties:
                   type:
                     type: string
+                    description: The type of the error.
                   message:
                     type: string
+                    description: A human-readable description of the error.
                   params:
                     type: object
+                    description: Additional information that might be present if the error is related to a specific parameter or payload field.
                     additionalProperties:
                       type: string
           examples:
@@ -32,7 +38,9 @@ components:
                   params:
                     measurement: '\"measurement\" does not match any of the allowed types'
     '404':
-      description: Not Found
+      description: |
+        If the API couldn't find the requested resource, it returns status `400 Not Found`
+        and a body containing more information about the error.
       content:
         application/json:
           schema:
@@ -57,7 +65,9 @@ components:
                   type: not_found
                   message: Couldn't find the requested item.
     measurements422:
-      description: Unprocessable Entity
+      description: |
+        If the API couldn't find suitable probes for your request, it returns status `422 Unprocessable Content` and a body with more
+        information about the error. Please modify your request before trying again.
       content:
         application/json:
           schema:
@@ -82,7 +92,9 @@ components:
                   type: no_probes_found
                   message: No suitable probes found.
     measurements429:
-      description: Too Many Requests
+#      TODO: add Please review our [API rate limits](https://github.com/jsdelivr/globalping).
+      description: |
+        If you've exceeded the API rate limit, you'll receive status `429 Too Many Requests` and a body containing more information about the error.
       content:
         application/json:
           schema:
@@ -107,7 +119,9 @@ components:
                   type: rate_limit_exceeded
                   message: API rate limit exceeded.
     measurements202:
-      description: Accepted
+      description: |
+        If the API accepted the request for processing, it returns status `202 Accepted` and a body containing the ID of the newly created measurement.
+        You can use the URL from the `Location` header to retrieve the measurement status.
       headers:
         Location:
           $ref: 'headers.yaml#/components/headers/MeasurementLocation'
@@ -131,7 +145,8 @@ components:
             '0':
               $ref: 'examples.yaml#/components/examples/createMeasurementResponse'
     measurement200:
-      description: Success
+      description: |
+        A successful request returns status `200 OK` and a body containing the requested measurement results.
       content:
         application/json:
           schema:
@@ -153,7 +168,8 @@ components:
             httpMeasurement:
               $ref: 'examples.yaml#/components/examples/getHttpMeasurementResponse'
     probes200:
-      description: Success
+      description: |
+        A successful request returns status `200 OK` and a body containing a list of all probes currently online and their metadata.
       content:
         application/json:
           schema: