@serenity-js/rest 3.25.0 → 3.25.2

package/lib/screenplay/models/HeadRequest.d.ts

@@ -34,20 +34,20 @@ export declare class HeadRequest extends HTTPRequest {
      *
      * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
      * it gets concatenated with the URL provided to the Axios instance
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * @param resourceUri
-     *  The URI where the {@apilink Actor}
-     *  should send the {@apilink HTTPRequest}
+     *  The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     *  should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
      */
     static to(resourceUri: Answerable<string>): HeadRequest;
     /**
      * Overrides the default Axios request configuration provided
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * #### Learn more
-     * - {@apilink Answerable}
-     * - {@apilink WithAnswerableProperties}
+     * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config

package/lib/screenplay/models/HeadRequest.js

@@ -36,22 +36,22 @@ class HeadRequest extends HTTPRequest_1.HTTPRequest {
      *
      * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
      * it gets concatenated with the URL provided to the Axios instance
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * @param resourceUri
-     *  The URI where the {@apilink Actor}
-     *  should send the {@apilink HTTPRequest}
+     *  The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     *  should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
      */
     static to(resourceUri) {
         return new HeadRequest(resourceUri);
     }
     /**
      * Overrides the default Axios request configuration provided
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * #### Learn more
-     * - {@apilink Answerable}
-     * - {@apilink WithAnswerableProperties}
+     * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config

package/lib/screenplay/models/OptionsRequest.d.ts

@@ -37,20 +37,20 @@ export declare class OptionsRequest extends HTTPRequest {
      *
      * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
      * it gets concatenated with the URL provided to the Axios instance
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * @param resourceUri
-     *  The URI where the {@apilink Actor}
-     *  should send the {@apilink HTTPRequest}
+     *  The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     *  should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
      */
     static to(resourceUri: Answerable<string>): OptionsRequest;
     /**
      * Overrides the default Axios request configuration provided
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * #### Learn more
-     * - {@apilink Answerable}
-     * - {@apilink WithAnswerableProperties}
+     * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config

package/lib/screenplay/models/OptionsRequest.js

@@ -39,22 +39,22 @@ class OptionsRequest extends HTTPRequest_1.HTTPRequest {
      *
      * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
      * it gets concatenated with the URL provided to the Axios instance
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * @param resourceUri
-     *  The URI where the {@apilink Actor}
-     *  should send the {@apilink HTTPRequest}
+     *  The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     *  should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
      */
     static to(resourceUri) {
         return new OptionsRequest(resourceUri);
     }
     /**
      * Overrides the default Axios request configuration provided
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * #### Learn more
-     * - {@apilink Answerable}
-     * - {@apilink WithAnswerableProperties}
+     * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config

package/lib/screenplay/models/PatchRequest.d.ts

@@ -34,11 +34,11 @@ export declare class PatchRequest extends HTTPRequest {
      *
      * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
      * it gets concatenated with the URL provided to the Axios instance
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * @param resourceUri
-     *  The URI where the {@apilink Actor}
-     *  should send the {@apilink HTTPRequest}
+     *  The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     *  should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
      */
     static to(resourceUri: Answerable<string>): PatchRequest;
     /**
@@ -50,11 +50,11 @@ export declare class PatchRequest extends HTTPRequest {
     with(data: Answerable<any>): PatchRequest;
     /**
      * Overrides the default Axios request configuration provided
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * #### Learn more
-     * - {@apilink Answerable}
-     * - {@apilink WithAnswerableProperties}
+     * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config

package/lib/screenplay/models/PatchRequest.js

@@ -36,11 +36,11 @@ class PatchRequest extends HTTPRequest_1.HTTPRequest {
      *
      * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
      * it gets concatenated with the URL provided to the Axios instance
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * @param resourceUri
-     *  The URI where the {@apilink Actor}
-     *  should send the {@apilink HTTPRequest}
+     *  The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     *  should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
      */
     static to(resourceUri) {
         return new PatchRequest(resourceUri);
@@ -56,11 +56,11 @@ class PatchRequest extends HTTPRequest_1.HTTPRequest {
     }
     /**
      * Overrides the default Axios request configuration provided
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * #### Learn more
-     * - {@apilink Answerable}
-     * - {@apilink WithAnswerableProperties}
+     * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config

package/lib/screenplay/models/PostRequest.d.ts

@@ -74,11 +74,11 @@ export declare class PostRequest extends HTTPRequest {
      *
      * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
      * it gets concatenated with the URL provided to the Axios instance
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * @param resourceUri
-     *  The URI where the {@apilink Actor}
-     *  should send the {@apilink HTTPRequest}
+     *  The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     *  should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
      */
     static to(resourceUri: Answerable<string>): PostRequest;
     /**
@@ -90,11 +90,11 @@ export declare class PostRequest extends HTTPRequest {
     with(data: Answerable<any>): PostRequest;
     /**
      * Overrides the default Axios request configuration provided
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * #### Learn more
-     * - {@apilink Answerable}
-     * - {@apilink WithAnswerableProperties}
+     * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config

package/lib/screenplay/models/PostRequest.js

@@ -76,11 +76,11 @@ class PostRequest extends HTTPRequest_1.HTTPRequest {
      *
      * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
      * it gets concatenated with the URL provided to the Axios instance
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * @param resourceUri
-     *  The URI where the {@apilink Actor}
-     *  should send the {@apilink HTTPRequest}
+     *  The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     *  should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
      */
     static to(resourceUri) {
         return new PostRequest(resourceUri);
@@ -96,11 +96,11 @@ class PostRequest extends HTTPRequest_1.HTTPRequest {
     }
     /**
      * Overrides the default Axios request configuration provided
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * #### Learn more
-     * - {@apilink Answerable}
-     * - {@apilink WithAnswerableProperties}
+     * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config

package/lib/screenplay/models/PutRequest.d.ts

@@ -44,11 +44,11 @@ export declare class PutRequest extends HTTPRequest {
      *
      * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
      * it gets concatenated with the URL provided to the Axios instance
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * @param resourceUri
-     *  The URI where the {@apilink Actor}
-     *  should send the {@apilink HTTPRequest}
+     *  The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     *  should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
      */
     static to(resourceUri: Answerable<string>): PutRequest;
     /**
@@ -60,11 +60,11 @@ export declare class PutRequest extends HTTPRequest {
     with(data: Answerable<any>): PutRequest;
     /**
      * Overrides the default Axios request configuration provided
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * #### Learn more
-     * - {@apilink Answerable}
-     * - {@apilink WithAnswerableProperties}
+     * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config

package/lib/screenplay/models/PutRequest.js

@@ -46,11 +46,11 @@ class PutRequest extends HTTPRequest_1.HTTPRequest {
      *
      * When the `resourceUri` is not a fully qualified URL but a path, such as `/products/2`,
      * it gets concatenated with the URL provided to the Axios instance
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * @param resourceUri
-     *  The URI where the {@apilink Actor}
-     *  should send the {@apilink HTTPRequest}
+     *  The URI where the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     *  should send the [`HTTPRequest`](https://serenity-js.org/api/rest/class/HTTPRequest/)
      */
     static to(resourceUri) {
         return new PutRequest(resourceUri);
@@ -66,11 +66,11 @@ class PutRequest extends HTTPRequest_1.HTTPRequest {
     }
     /**
      * Overrides the default Axios request configuration provided
-     * when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     * when the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      *
      * #### Learn more
-     * - {@apilink Answerable}
-     * - {@apilink WithAnswerableProperties}
+     * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * - [`WithAnswerableProperties`](https://serenity-js.org/api/core/#WithAnswerableProperties)
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
      *
      * @param {Answerable<WithAnswerableProperties<AxiosRequestConfig>>} config

package/lib/screenplay/questions/LastResponse.d.ts

@@ -1,8 +1,8 @@
 import type { QuestionAdapter } from '@serenity-js/core';
 import type { RawAxiosResponseHeaders } from 'axios';
 /**
- * Provides access to the properties of the last {@apilink AxiosResponse} object,
- * cached on the {@apilink Ability|ability} to {@apilink CallAnApi}.
+ * Provides access to the properties of the last [`AxiosResponse`](https://axios-http.com/docs/res_schema) object,
+ * cached on the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/).
  *
  * ## Verify response to a GET request
  *
@@ -64,14 +64,14 @@ import type { RawAxiosResponseHeaders } from 'axios';
  */
 export declare class LastResponse {
     /**
-     * Retrieves the status code of the {@apilink LastResponse|last response}
+     * Retrieves the status code of the [last response](https://serenity-js.org/api/rest/class/LastResponse/)
      *
      * #### Learn more
      * - [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
      */
     static status(): QuestionAdapter<number>;
     /**
-     * Retrieves the body of the {@apilink LastResponse|last response}
+     * Retrieves the body of the [last response](https://serenity-js.org/api/rest/class/LastResponse/)
      *
      * #### A type-safe approach using generics
      *
@@ -146,7 +146,7 @@ export declare class LastResponse {
      */
     static body<T = any>(): QuestionAdapter<T>;
     /**
-     * Retrieves a header of the {@apilink LastResponse|last response}, identified by `name`
+     * Retrieves a header of the [last response](https://serenity-js.org/api/rest/class/LastResponse/), identified by `name`
      *
      * ## Asserting on a header
      *
@@ -167,7 +167,7 @@ export declare class LastResponse {
      */
     static header(name: string): QuestionAdapter<string>;
     /**
-     * Retrieves all the headers of the {@apilink LastResponse|last response}.
+     * Retrieves all the headers of the [last response](https://serenity-js.org/api/rest/class/LastResponse/).
      *
      * ## Asserting on a header
      *

package/lib/screenplay/questions/LastResponse.js

@@ -4,8 +4,8 @@ exports.LastResponse = void 0;
 const core_1 = require("@serenity-js/core");
 const abilities_1 = require("../abilities");
 /**
- * Provides access to the properties of the last {@apilink AxiosResponse} object,
- * cached on the {@apilink Ability|ability} to {@apilink CallAnApi}.
+ * Provides access to the properties of the last [`AxiosResponse`](https://axios-http.com/docs/res_schema) object,
+ * cached on the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/).
  *
  * ## Verify response to a GET request
  *
@@ -67,7 +67,7 @@ const abilities_1 = require("../abilities");
  */
 class LastResponse {
     /**
-     * Retrieves the status code of the {@apilink LastResponse|last response}
+     * Retrieves the status code of the [last response](https://serenity-js.org/api/rest/class/LastResponse/)
      *
      * #### Learn more
      * - [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
@@ -78,7 +78,7 @@ class LastResponse {
         });
     }
     /**
-     * Retrieves the body of the {@apilink LastResponse|last response}
+     * Retrieves the body of the [last response](https://serenity-js.org/api/rest/class/LastResponse/)
      *
      * #### A type-safe approach using generics
      *
@@ -157,7 +157,7 @@ class LastResponse {
         });
     }
     /**
-     * Retrieves a header of the {@apilink LastResponse|last response}, identified by `name`
+     * Retrieves a header of the [last response](https://serenity-js.org/api/rest/class/LastResponse/), identified by `name`
      *
      * ## Asserting on a header
      *
@@ -182,7 +182,7 @@ class LastResponse {
         });
     }
     /**
-     * Retrieves all the headers of the {@apilink LastResponse|last response}.
+     * Retrieves all the headers of the [last response](https://serenity-js.org/api/rest/class/LastResponse/).
      *
      * ## Asserting on a header
      *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@serenity-js/rest",
-  "version": "3.25.0",
-  "description": "Test REST APIs with Serenity/JS",
+  "version": "3.25.2",
+  "description": "Serenity/JS Screenplay Pattern library for interacting with REST and other HTTP-based services, supporting comprehensive API testing and blended testing scenarios",
   "author": {
     "name": "Jan Molak",
     "email": "jan.molak@smartcodeltd.co.uk",
@@ -46,18 +46,18 @@
     "node": "^16.13 || ^18.12 || ^20"
   },
   "dependencies": {
-    "@serenity-js/core": "3.25.0",
+    "@serenity-js/core": "3.25.2",
     "agent-base": "7.1.1",
     "axios": "1.7.2",
     "http-proxy-agent": "7.0.2",
     "https-proxy-agent": "7.0.5",
-    "lru-cache": "10.3.0",
+    "lru-cache": "10.4.3",
     "proxy-from-env": "1.1.0",
     "tiny-types": "1.22.0"
   },
   "devDependencies": {
     "@integration/testing-tools": "3.0.0",
-    "@serenity-js/assertions": "3.25.0",
+    "@serenity-js/assertions": "3.25.2",
     "@types/chai": "4.3.16",
     "@types/mocha": "10.0.7",
     "axios-mock-adapter": "1.22.0",
@@ -67,5 +67,5 @@
     "ts-node": "10.9.2",
     "typescript": "5.2.2"
   },
-  "gitHead": "22657b685b6002f75b2569db54f4bea31ab91d12"
+  "gitHead": "98b68da1e04a8fcbb255dca509b7bc9c322a3b6b"
 }

package/src/screenplay/abilities/CallAnApi.ts

@@ -11,8 +11,9 @@ import type { AxiosRequestConfigDefaults} from '../../io';
 import { createAxios } from '../../io';
 
 /**
- * An {@apilink Ability} that wraps [axios client](https://axios-http.com/docs/api_intro) and enables
- * the {@apilink Actor} to {@apilink Send} {@apilink HTTPRequest|HTTP requests} to HTTP APIs.
+ * An [ability](https://serenity-js.org/api/core/class/Ability/) that wraps [axios client](https://axios-http.com/docs/api_intro) and enables
+ * the [actor](https://serenity-js.org/api/core/class/Actor/) to [send](https://serenity-js.org/api/rest/class/Send/)
+ * [HTTP requests](https://serenity-js.org/api/rest/class/HTTPRequest/) to HTTP APIs.
  *
  * `CallAnApi` uses [`proxy-from-env`](https://www.npmjs.com/package/proxy-from-env) and an approach
  * described in ["Node.js Axios behind corporate proxies"](https://janmolak.com/node-js-axios-behind-corporate-proxies-8b17a6f31f9d)
@@ -191,7 +192,7 @@ import { createAxios } from '../../io';
  *
  * ### Serenity/JS defaults
  *
- * When using {@apilink CallAnApi.at} or {@apilink CallAnApi.using} with a configuration object, Serenity/JS
+ * When using [`CallAnApi.at`](https://serenity-js.org/api/rest/class/CallAnApi/#at) or [`CallAnApi.using`](https://serenity-js.org/api/rest/class/CallAnApi/#using) with a configuration object, Serenity/JS
  * merges your [Axios request configuration](https://axios-http.com/docs/req_config) with the following defaults:
  * - `timeout`: 10 seconds
  *
@@ -228,7 +229,7 @@ import { createAxios } from '../../io';
  *
  * ### Using API-specific actors
  *
- * To create API-specific actors, configure your [test runner](/handbook/test-runners/) with a {@apilink Cast}
+ * To create API-specific actors, configure your [test runner](https://serenity-js.org/handbook/test-runners/) with a [cast](https://serenity-js.org/api/core/class/Cast/)
  * that gives your actors appropriate abilities based, for example, on their name:
  *
  * ```ts
@@ -252,7 +253,7 @@ import { createAxios } from '../../io';
  * beforeEach(() => engage(new MyActors()))
  * ```
  *
- * Next, retrieve the appropriate actor in your test scenario using {@apilink actorCalled}, for example:
+ * Next, retrieve the appropriate actor in your test scenario using [`actorCalled`](https://serenity-js.org/api/core/function/actorCalled/), for example:
  *
  * ```ts
  * import { describe, it, beforeEach } from 'mocha'
@@ -324,7 +325,7 @@ export class CallAnApi extends Ability {
     private lastResponse: AxiosResponse;
 
     /**
-     * Produces an {@apilink Ability|ability} to call a REST API at a specified `baseURL`;
+     * Produces an [ability](https://serenity-js.org/api/core/class/Ability/) to call a REST API at a specified `baseURL`;
      *
      * This is the same as invoking `CallAnApi.using({ baseURL: 'https://example.org' })`
      *
@@ -339,7 +340,7 @@ export class CallAnApi extends Ability {
     }
 
     /**
-     * Produces an {@apilink Ability|ability} to call an HTTP API using the given Axios instance,
+     * Produces an [ability](https://serenity-js.org/api/core/class/Ability/) to call an HTTP API using the given Axios instance,
      * or an Axios request configuration object.
      *
      * When you provide an [Axios configuration object](https://axios-http.com/docs/req_config),
@@ -351,7 +352,7 @@ export class CallAnApi extends Ability {
      * When you provide an Axios instance, it's enhanced with proxy support and no other modifications are made.
      *
      * If you don't want Serenity/JS to augment or modify your Axios instance in any way,
-     * please use the {@apilink CallAnApi.constructor} directly.
+     * please use the [`CallAnApi.constructor`](https://serenity-js.org/api/rest/class/CallAnApi/#constructor) directly.
      *
      * @param axiosInstanceOrConfig
      */
@@ -372,8 +373,8 @@ export class CallAnApi extends Ability {
 
     /**
      * Allows for the original Axios config to be changed after
-     * the {@apilink Ability|ability} to {@apilink CallAnApi}
-     * has been instantiated and given to the {@apilink Actor}.
+     * the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/)
+     * has been instantiated and given to the [`Actor`](https://serenity-js.org/api/core/class/Actor/).
      *
      * #### Learn more
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
@@ -386,7 +387,7 @@ export class CallAnApi extends Ability {
 
     /**
      * Sends an HTTP request to a specified url.
-     * Response will be cached and available via {@apilink mapLastResponse}
+     * Response will be cached and available via [`CallAnApi.mapLastResponse`](https://serenity-js.org/api/rest/class/CallAnApi/#mapLastResponse).
      *
      * #### Learn more
      * - [AxiosRequestConfig](https://axios-http.com/docs/req_config)
@@ -394,7 +395,8 @@ export class CallAnApi extends Ability {
      *
      * @param config
      *  Axios request configuration, which can be used to override the defaults
-     *  provided when the {@apilink Ability|ability} to {@apilink CallAnApi} was instantiated.
+     *  provided when the [ability](https://serenity-js.org/api/core/class/Ability/)
+     *  to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) was instantiated.
      */
     async request(config: AxiosRequestConfig): Promise<AxiosResponse> {
         let url: string;
@@ -429,8 +431,8 @@ export class CallAnApi extends Ability {
     }
 
     /**
-     * Resolves the final URL, based on the {@apilink AxiosRequestConfig} provided
-     * and any defaults that the {@apilink AxiosInstance} has been configured with.
+     * Resolves the final URL, based on the [`AxiosRequestConfig`](https://axios-http.com/docs/req_config) provided
+     * and any defaults that the [`AxiosInstance`](https://axios-http.com/docs/instance) has been configured with.
      *
      * Note that unlike Axios, this method uses the Node.js [WHATWG URL API](https://nodejs.org/api/url.html#new-urlinput-base)
      * to ensure URLs are correctly resolved.
@@ -447,7 +449,7 @@ export class CallAnApi extends Ability {
 
     /**
      * Maps the last cached response to another type.
-     * Useful when you need to extract a portion of the {@apilink AxiosResponse} object.
+     * Useful when you need to extract a portion of the [`AxiosResponse`](https://axios-http.com/docs/res_schema) object.
      *
      * #### Learn more
      * - [AxiosResponse](https://axios-http.com/docs/res_schema)

package/src/screenplay/interactions/ChangeApiConfig.ts

@@ -5,8 +5,8 @@ import { URL } from 'url';
 import { CallAnApi } from '../abilities';
 
 /**
- * Changes configuration of the {@apilink Ability|ability} to {@apilink CallAnApi}
- * that the {@apilink Actor|actor} executing this {@apilink Interaction|interaction} has been configured with.
+ * Changes configuration of the [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/)
+ * that the [actor](https://serenity-js.org/api/core/class/Actor/) executing this [interaction](https://serenity-js.org/api/core/class/Interaction/) has been configured with.
  *
  * ## Changing API URL for all subsequent requests
  *
@@ -90,7 +90,7 @@ import { CallAnApi } from '../abilities';
  * ## Handling sensitive information
  *
  * By design, any data handled by an actor appears in Serenity/JS reports.
- * To prevent the exposure of any sensitive information, such as passwords or tokens, you should use {@apilink Masked}.
+ * To prevent the exposure of any sensitive information, such as passwords or tokens, you should use [`Masked`](https://serenity-js.org/api/core/class/Masked/).
  * 
  * ```ts
  * import { actorCalled, Masked } from '@serenity-js/core'
@@ -113,8 +113,8 @@ import { CallAnApi } from '../abilities';
 export class ChangeApiConfig {
 
     /**
-     * Instructs the {@apilink Actor|actor} to change the base URL
-     * of their {@apilink Ability|ability} to {@apilink CallAnApi}
+     * Instructs the [actor](https://serenity-js.org/api/core/class/Actor/) to change the base URL
+     * of their [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/)
      *
      * @param newApiUrl
      */
@@ -123,8 +123,8 @@ export class ChangeApiConfig {
     }
 
     /**
-     * Instructs the {@apilink Actor|actor} to change the port configured in the base URL
-     * of their {@apilink Ability|ability} to {@apilink CallAnApi}
+     * Instructs the [actor](https://serenity-js.org/api/core/class/Actor/) to change the port configured in the base URL
+     * of their [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/)
      *
      * @param newApiPort
      */
@@ -133,10 +133,10 @@ export class ChangeApiConfig {
     }
 
     /**
-     * Instructs the {@apilink Actor|actor} to change the configuration of the {@apilink AxiosInstance}
-     * used by their {@apilink Ability|ability} to {@apilink CallAnApi}
-     * and set an HTTP request header for any subsequent {@apilink HTTPRequest|HTTPRequests}
-     * issued via {@apilink Send}.
+     * Instructs the [actor](https://serenity-js.org/api/core/class/Actor/) to change the configuration of the [`AxiosInstance`](https://axios-http.com/docs/instance)
+     * used by their [ability](https://serenity-js.org/api/core/class/Ability/) to [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/)
+     * and set an HTTP request header for any subsequent [HTTP requests](https://serenity-js.org/api/rest/class/HTTPRequest/)
+     * issued via [`Send`](https://serenity-js.org/api/rest/class/Send/).
      *
      * @param name
      * @param value