chore(release): Release v3.5.0

Author: javierbrea

versioned_docs/version-3.5.0/api-mocks-server-api.md

@@ -0,0 +1,63 @@
+---
+id: api-programmatic-usage
+title: Programmatic usage
+description: Programmatic usage of Mocks Server
+keywords:
+  - mocks server
+  - programmatic
+  - api
+  - advanced usage
+  - customization
+---
+
+## Core usage
+
+The server can be instantiated and started programmatically using the [@mocks-server/core](https://www.npmjs.com/package/@mocks-server/core) package, which does not include plugins.
+
+You can also register your own or another existing plugins, so you could even create your custom distribution with plugins of your choice.
+
+### Example
+
+```javascript
+const Core = require("@mocks-server/core");
+const AdminApi = require("@mocks-server/plugin-admin-api");
+const InquirerCli = require("@mocks-server/plugin-inquirer-cli");
+
+const core = new Core({
+  config: {
+    readFile: false,
+    readEnvironment: false,
+    readArguments: false,
+  },
+  plugins: {
+    register: [AdminApi, InquirerCli]
+  },
+});
+
+core.init({
+    server: {
+      port: 3500
+    },
+    mocks: {
+      delay: 1000
+    },
+    log: "debug"
+  })
+  .then(core.start);
+```
+
+## Core API
+
+#### `new Core([config][,advancedOptions])` 
+
+##### Arguments
+
+* `config` _(Object)_: Object containing configuration properties and options as described in the [configuration chapter](configuration-options.md).
+* `advancedOptions` _(Object)_: Object containing advanced options for creating a core instance. It may contain any of next properties:
+  * `pkg` _(Object)_: It allows to change the package name and version that is checked by the update notifier. It is useful when publishing custom Mocks Server distributions, so you can check your package version instead of the default one, which is the current version of `@mocks-server/core`. It must be an object containing next properties:
+    * `name` _(String)_ : Name of the package.
+    * `version` _(String)_: Installed version of the package.
+
+## Core instance API
+
+Please read the [`core` API chapter](api-mocks-server-api.md) to know all available methods and getters in the `core` instance that the `Core` class returns.

versioned_docs/version-3.5.0/api-programmatic-usage.md

@@ -0,0 +1,24 @@
+---
+id: api-routes-and-mocks
+title: Routes and Mocks
+description: Routes and Mocks API
+keywords:
+  - mocks server
+  - api
+  - routes
+  - mocks
+  - properties
+  - options
+---
+
+## Preface
+
+The main concepts to understand when working with Mocks Server are `Routes`, `Route variants` and `Mocks`. That's why their APIs are explained in the "Get started" section.
+
+## Routes
+
+Read the [Routes chapter in the "Get started"](get-started-routes.md) section for a detailed explanation about how to define routes and all of its available properties.
+
+## Mocks
+
+Read the [Mocks chapter in the "Get started"](get-started-mocks.md) section for a detailed explanation about how to define mocks and all of its available properties.

versioned_docs/version-3.5.0/api-routes-and-mocks.md

@@ -0,0 +1,171 @@
+---
+id: api-routes-handler
+title: Routes Handler
+description: How to add custom routes handlers
+keywords:
+  - mocks server
+  - customization
+  - routes
+  - routes variants
+  - handler
+  - format
+---
+
+## What is a Routes Handler?
+
+A "Routes handler" is the element at charge of handling the [routes variants declarations](get-started-routes.md), and sending the appropriate response.
+
+Mocks Server includes only one Routes Handler by default, which accepts routes variants declared in the [format described in the `routes` chapter](get-started-routes.md), but __you can add your own route variants formats__.
+
+This feature, combined with the [plugins development](plugins-developing-plugins.md), gives you the possibility of adding to Mocks Server almost every new feature you want.
+
+## Creating custom Routes Handlers
+
+A Routes Handler should be defined as a `Class` containing:
+
+#### `static get id()`
+
+This static getter will be used to recognize the Routes Handler. When defining a route variant, the handler to be used can be defined using the `handler` property. That property in route variants should be the `id` of the Route Handler to be used.
+
+#### `static get version()`
+
+This property was added in v3.5 in order to allow to adapt to the next major version without breaking changes. It must return "4" in order to be able to use the API described in this page. Please read other version docs to check old handlers APIs.
+
+#### `static get deprecated()`
+
+This property was added in v3.5 in order to allow to adapt to the next major version without breaking changes. It should be added to Handlers using the old API in order to inform users that they shouldn't use it because it will be deprecated in v4. An alert will be added if this getter returns `true`.
+
+#### `static get validationSchema()`
+
+This static getter must return a JSON schema defining the specific properties required by the handler. It will be used by the core to validate the route variants of this type. `ajv` is used under the hood to perform validations. Take into account next points when defining the json schema:
+
+* You must only define those properties defined in the `response` property of the variant definition.
+* Mocks Server supports a special JSON schema keyword named `instanceof`. You can use it to indicate that a property must be an instance of a `Function`, or a `RegExp` for example.
+
+#### `constructor(response, core)`
+
+* `response`: All properties in the `response` property of the route variant definition.
+* `core`: The [`core` instance](api-mocks-server-api.md), but with some methods specifically scoped for each route variant, such as `core.logger` and `core.alerts`, which are namespaced using each route variant id. So, logs or alerts from each different route variant can be easily identified.
+
+#### `middleware(req, res, next)`
+
+This is the middleware that will be called when the route url matches and the specific variant type corresponds to this route handler (it is equal to the route handler id).
+
+#### `get preview()`
+
+This getter should return a plain object containing an approached preview of the response that will be sent when the route variant is used. This is useful to provide information to other plugins or Mocks Server interfaces. If you have not enough information to predict the response (as in the case of `middlewares` handler, for example), you should return `null`.
+
+## Example
+
+Here you have an example of how a custom Routes Handler should be defined:
+
+```js
+// ./CustomRoutesHandler.js
+
+class CustomRoutesHandler {
+  static get id() {
+    return "error";
+  }
+
+  static get version() {
+    return "4";
+  }
+
+  static get validationSchema() {
+    return {
+      type: "object",
+      properties: {
+        code: {
+          type: "number",
+        },
+        message: {
+          type: "string",
+        },
+      },
+      required: ["code", "message"],
+      additionalProperties: false,
+    };
+  }
+
+  constructor(response, core) {
+    this._code = response.code;
+    this._message = response.message;
+    this._core = core;
+  }
+
+  middleware(req, res, next) {
+    // Next log automatically includes the route variant id
+    this._core.logger.info("Sending response");
+    res.status(this._code);
+    res.send({
+      message: this._message
+    });
+  }
+
+  get preview() {
+    return {
+      body: {
+        message: this._message
+      },
+      status: this._code,
+    };
+  }
+}
+
+module.exports = CustomRoutesHandler;
+```
+
+Then you can add your custom Routes Handler using the configuration file:
+
+```javascript
+// mocks.config.js
+
+const CustomRoutesHandler = require("./CustomRoutesHandler");
+
+module.exports = {
+  routesHandlers: [CustomRoutesHandler],
+  server: {
+    port: 3100,
+  },
+  mocks: {
+    selected: "base",
+  },
+};
+```
+
+:::note
+You can also add Route Handlers programmatically using the [`core.addRoutesHandler` method](api-mocks-server-api.md) (useful to be used from [plugins](plugins-developing-plugins.md), for example)
+:::
+
+And now, you can use the custom handler when defining route variants:
+
+```js
+// mocks/routes/users.js
+
+module.exports = [
+  {
+    id: "get-users",
+    url: "/api/users",
+    method: "GET",
+    variants: [
+      {
+        id: "error-400",
+        handler: "error", // id of the handler to be used
+        response: { // object that the handler will receive
+          code: 400,
+          message: "Error message",
+        },
+      }
+      {
+        // This one will use the "json" handler
+        id: "empty",
+        handler: "json",
+        response: {
+          status: 200,
+          body: []
+        }
+      },
+    ]
+  }
+]
+```