Skip to content

Commit

Permalink
Release/next (#152)
Browse files Browse the repository at this point in the history
* Use new user profile type

* Prepare new release

* Remove old docs and add docs for deploy option

* Package lock

* Rewrite data files docs and remove old rf to v1.16.0

* Update docs for JSON schema improved support

* Add JSON schema tutorial

* Update docs with new tool

* Remove old sponsor images

* docs image change

* Add doc for deploy custom subdomain

* Add docs for object merging helpers update

* add docs

* Add changelog

* Changelog formatting
  • Loading branch information
255kb authored Dec 5, 2024
1 parent f87b08f commit 36110e5
Show file tree
Hide file tree
Showing 401 changed files with 2,862 additions and 1,767 deletions.
1 change: 0 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,6 @@ Some screenshots still need to be created manually:
Some screenshots are not changing between versions:

- `/docs/latest/route-responses/dynamic-rules/`: the rules order schema
- `/docs/latest/mockoon-data-files/data-storage-location/`: the "old system" screenshot

> Both are located in the `images/docs/shared` folder.
Expand Down
2 changes: 1 addition & 1 deletion components/footer.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ const Footer: FunctionComponent<{
</li>
<li className='mb-2'>
{/* Do not use <Link>, as routes with a dot inside get rewritten without trailing slash */}
<a href='/releases/9.0.0/' className='text-reset'>
<a href='/releases/9.1.0/' className='text-reset'>
Releases
</a>
</li>
Expand Down
2 changes: 1 addition & 1 deletion components/markdown.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ const Markdown: FunctionComponent<{
src={src as string}
width={width}
height={height}
className={`img-fluid mx-auto d-block img-shadow mt-8 ${
className={`img-fluid mx-auto d-block img-shadow mt-6 ${
hasSub ? 'mb-2' : 'mb-8'
} rounded`}
/>
Expand Down
2 changes: 1 addition & 1 deletion components/nav.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -320,7 +320,7 @@ const Nav: FunctionComponent = function () {
Blog
</Link>
<a
href='/releases/9.0.0/'
href='/releases/9.1.0/'
className={`dropdown-item ${
router.pathname === '/releases' ||
router.pathname === '/releases/[version]'
Expand Down
4 changes: 2 additions & 2 deletions content/docs/latest/about.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ This allows you to migrate from one version to another without worrying about co

### Major versions

While the desktop application can easily **migrate from one version to another** (including major versions), this is not the case for the CLI or serverless package. When you are using one of your [data files](docs:mockoon-data-files/data-storage-location) with the CLI or serverless package, or sharing it with your team, you need to make sure that the data file schema is compatible with the version you or your team is using.
While the desktop application can easily **migrate from one version to another** (including major versions), this is not the case for the CLI or serverless package. When you are using one of your [data files](docs:mockoon-data-files/data-files-location) with the CLI or serverless package, or sharing it with your team, you need to make sure that the data file schema is compatible with the version you or your team is using.

Every time we introduce a **breaking change** in the data file schema (e.g. new feature) we release a **new major version**. We recommend that you always migrate simultaneously to the same major version for all the desktop applications and packages you are using.

Expand All @@ -44,7 +44,7 @@ When building libraries, the definition of a **breaking change** is usually stra

Also, as we have **multiple components** (desktop application, CLI, serverless package), we have to consider the impact of a change on all these components while avoiding a too-strict definition of a breaking change that would mandate a new major version for every release.

Our definition of a breaking change is a change impacting the [**data schema**](docs:mockoon-data-files/data-storage-location) and creating a **compatibility issue** between the applications and packages.
Our definition of a breaking change is a change impacting the [**data schema**](docs:mockoon-data-files/data-files-location) and creating a **compatibility issue** between the applications and packages.

Examples of **schema changes** that would require a **new major version**:

Expand Down
2 changes: 1 addition & 1 deletion content/docs/latest/api-endpoints/crud-routes.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ The CRUD route will work with any content stored in your data bucket: valid JSON
### Resetting the data bucket content

The data bucket content is generated when the server starts, and its state persists between calls. However, its state will not be saved in the [data file](docs:mockoon-data-files/data-storage-location), and you can reset it to its initial state by restarting the mock API.
The data bucket content is generated when the server starts, and its state persists between calls. However, its state will not be saved in the [data file](docs:mockoon-data-files/data-files-location), and you can reset it to its initial state by restarting the mock API.

## CRUD route differences

Expand Down
2 changes: 1 addition & 1 deletion content/docs/latest/api-endpoints/folders.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,5 +25,5 @@ The server will create the endpoints in the same order they appear in the list,

## Repairing the data file

If Mockoon's [data file](docs:mockoon-data-files/data-storage-location) has broken references due to improper manipulation of the JSON, such as missing routes or nonexistent folders, it will automatically be repaired upon loading.
If Mockoon's [data file](docs:mockoon-data-files/data-files-location) has broken references due to improper manipulation of the JSON, such as missing routes or nonexistent folders, it will automatically be repaired upon loading.
If a route or folder does not exist, it will be automatically removed. On the other hand, unlisted routes and folders will be added back to the root level.
2 changes: 1 addition & 1 deletion content/docs/latest/api-endpoints/routing.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,6 @@ You can **disable a route** by clicking on the **Toggle route** entry in the rou

You can also disable all routes in a folder by using the **Toggle direct child routes** entry in the folder dropdown menu.

When running your mock API using the [CLI](/cli/), you can [disable routes using the `--disable-routes` flag](https://github.com/mockoon/mockoon/tree/main/packages/cli#disabling-routes) followed by a route UUID or keyword/name or a folder keyword/name: `mockoon start --disable-routes myroute folder2`.
When running your mock API using the [CLI](/cli/), you can [disable routes using the `--disable-routes` flag](https://github.com/mockoon/mockoon/tree/main/packages/cli#disabling-routes) followed by a route UUID or keyword/name or a folder keyword/name: `mockoon start -d ./data.json --disable-routes myroute folder2`. You can also disable all routes by using a wildcard: `mockoon start -d ./data.json --disable-routes "*"`.

When using the [serverless package](/serverless/), you can [disable routes using the `disabledRoutes` option](https://github.com/mockoon/mockoon/tree/main/packages/serverless#disabling-routes).
19 changes: 18 additions & 1 deletion content/docs/latest/data-buckets/using-data-buckets.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,4 +80,21 @@ To store a JSON schema in a data bucket, create a new data bucket and paste your
}
```

You will then be able to reference this full schema in a rule's value field (e.g. `dataBucketNameOrId`), or a specific schema's property using the [object-path](https://www.npmjs.com/package/object-path) syntax (e.g. `dataBucketNameOrId.name`).
You will then be able to reference this schema in a **rule's value field** by using the data bucket's name or ID: `mySchemaBucket`.

A data bucket can also **store multiple schemas** on various properties:

```json
{
"name": {
"type": "string"
},
"age": {
"type": "number"
}
}
```

To access a specific schema stored in a property, you can use the following syntax (using the [object-path](https://www.npmjs.com/package/object-path) syntax) in the rule's value field: `dataBucketNameOrId.propertyName`. Example: `mySchemasBucket.name` or `mySchemasBucket.age`.

> 🛠️ We created an online tool to help you [**validate your JSON Schema**](/tools/json-schema-validator/) before using it in Mockoon.
19 changes: 11 additions & 8 deletions content/docs/latest/mockoon-cloud/api-mock-cloud-deployments.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,28 +18,31 @@ order: 901

You can **deploy an environment** to the cloud using the context menu in the local or cloud environments list and selecting **"Deploy to the cloud"**:

![context menus to deploy cloud environments{513x507}](/images/docs/static/mockoon-cloud/api-mock-cloud-deployments/deploy-environment-menu.png)
![context menus to deploy cloud environments{513x507}](docs-img:deploy-environment-menu.png)

In the deployment dialog, you can further customize the deployment by selecting the **visibility** of the environment:
In the deployment dialog, you can further customize your instance:

- **Public**: The environment will be accessible to anyone with the URL.
- **Private**: The environment will be accessible only to users with the URL and the **API key**.
- **Subdomain**: The default subdomain is generated automatically, but you can customize it to a unique value. The subdomain will be part of the instance URL (e.g. `https://{subdomain}.serverid.mockoon.app`).
- **Visibility**:
- **Public**: The environment will be accessible to anyone with the URL.
- **Private**: The environment will be accessible only to users with the URL and the **API key** (see [Instance URL and visibility](#instance-url-and-visibility) below).
- **Enable/disable the admin API**: Enable/disable the [admin API](docs:admin-api/overview) available on a running mock on the `/mockoon-admin` endpoint.

![deployment dialog{800x225}](/images/docs/static/mockoon-cloud/api-mock-cloud-deployments/deploy-environment-dialog.png)
![deployment dialog{799x267}](docs-img:deploy-environment-dialog.png)

After clicking the **"Deploy"** button, the environment will be uploaded to the cloud and will be accessible using the provided URL. In the management dialog, you can find the URL and the API key to access the environment. You can also re-deploy the environment or delete the instance:

![deployment management dialog{799x205}](/images/docs/static/mockoon-cloud/api-mock-cloud-deployments/deploy-environment-management-dialog.png)
![deployment management dialog{799x205}](docs-img:deploy-environment-management-dialog.png)

### Re-deploy or delete a cloud instance

In the management dialog, you can **re-deploy** the environment or **delete** the instance using the menu:

![deployment management dialog re-deploy or delete the instance menu{902x235}](/images/docs/static/mockoon-cloud/api-mock-cloud-deployments/deploy-environment-management-menu.png)
![deployment management dialog re-deploy or delete the instance menu{902x235}](docs-img:deploy-environment-management-menu.png)

## Instance URL and visibility

The instance will be deployed on a shared cloud infrastructure and will be accessible using a unique URL in the form of `https://mock-abcd1234.serverid.mockoon.app`. The URL will be displayed in the management dialog and can be shared with your team, clients, or class.
The instance will be deployed on a shared cloud infrastructure and will be accessible using a unique URL in the form of `https://mock-abcd1234.serverid.mockoon.app`. The URL will be displayed in the management dialog and can be shared with your team, clients, or class. You can also customize the subdomain part of the URL when deploying the environment.

The visibility of the environment can be set to **public** or **private**. Here are the differences between the two:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,27 +14,27 @@ order: 902

## Cloud vs local environments

The **local environment** is the default environment in Mockoon. It is [stored on your local machine](docs:mockoon-data-files/data-storage-location) and not synchronized with the cloud.
The **local environment** is the default environment in Mockoon. It is [stored on your local machine](docs:mockoon-data-files/data-files-location) and not synchronized with the cloud.

**Cloud environments** are stored on our servers, and a local copy is kept on each client's machine. You can easily **create a cloud copy** of your local environment or **convert an existing cloud environment** back to a local environment.

![Cloud and local environments menus{200x231}](/images/docs/static/mockoon-cloud/data-synchronization-team-collaboration/cloud-sync-menu.png)
![Cloud and local environments menus{200x231}](docs-img:cloud-sync-menu.png)

## Managing your cloud environments

### Create a cloud environment

There are multiple ways to **create a cloud environment**. You can use the context menu in the local environments list to create a cloud environment from a local one using "Duplicate to the cloud" or create a new cloud environment from scratch using "New cloud environment" from the cloud environments menu.

![context menus to create cloud environments{569x492}](/images/docs/static/mockoon-cloud/data-synchronization-team-collaboration/create-cloud-environment.png)
![context menus to create cloud environments{569x492}](docs-img:create-cloud-environment.png)

The new cloud environment will be created and synchronized with the cloud, together with a local copy. It will be available on all your devices (solo plan) and for all your team members (team/enterprise plans) once they connect to the cloud.

### Remove an environment from the cloud

You can **remove an environment** from the cloud using the context menu in the cloud environments list and selecting "Convert to local" or "Delete from cloud":

![context menu to convert a cloud environment to local{533x277}](/images/docs/static/mockoon-cloud/data-synchronization-team-collaboration/convert-cloud-to-local.png)
![context menu to convert a cloud environment to local{533x277}](docs-img:convert-cloud-to-local.png)

After converting an environment to local, it will be **permanently removed from the cloud** and **converted to a local environment** on all your devices (solo plan) and for all your team members (team/enterprise plans).

Expand All @@ -54,7 +54,7 @@ However, some parts of the environment definition cannot be edited simultaneousl

**Presence indicators** are displayed in the application to show who is currently **connected** and **editing** an environment. They are visible in the cloud environments list, indicating if a user is editing an environment (left side of the image). Additionally, presence indicators are shown at the top of the application, displaying the users currently connected to the cloud space (right side of the image).

![Presence indicators{668x157}](/images/docs/static/mockoon-cloud/data-synchronization-team-collaboration/presence-indicators.png)
![Presence indicators{668x157}](docs-img:presence-indicators.png)

> 💡 You can customize your display name in the [application settings](/account/info/) to make it easier for your team members to identify you.
Expand All @@ -64,25 +64,25 @@ Mockoon's synchronization and collaboration features are primarily designed to w

When you are offline, a warning is shown in the cloud environments list:

![#sub#Warning shown when the application is offline{391x209}](/images/docs/static/mockoon-cloud/data-synchronization-team-collaboration/offline-editing-warning.png)
![#sub#Warning shown when the application is offline{391x209}](docs-img:offline-editing-warning.png)

When you modify an environment while being offline and go back online, three scenarios can happen:

- **You made local changes**, but **the cloud version was not modified**: your local changes will be automatically **pushed** to the cloud.
- **You did not make local changes**, but **the cloud version was modified**: the cloud version will be pulled automatically to your local environment.
- **You made local changes**, and **the cloud version was modified**: you will be prompted to **choose** between **keeping** your local changes or **discarding** them.

![#sub#Dialog shown when the application detected a conflict{504x241}](/images/docs/static/mockoon-cloud/data-synchronization-team-collaboration/offline-conflict-warning.png)
![#sub#Dialog shown when the application detected a conflict{504x241}](docs-img:offline-conflict-warning.png)

> ⚠️ If multiple users edit the same environment while offline, **only one version of the environment will be kept** and the others will be discarded.
## Disconnection reasons

If you are disconnected from the cloud, the application will display a warning in the cloud environments list in the form of a orange or red cloud icon. Hovering over the icon will display the reason for the disconnection (e.g. incompatible version, etc.). You can also click on the icon to try to reconnect:

![#sub#Tooltip showing a regular disconnection{287x219}](/images/docs/static/mockoon-cloud/data-synchronization-team-collaboration/offline-reason-disconnected.png)
![#sub#Tooltip showing a regular disconnection{287x219}](docs-img:offline-reason-disconnected.png)

![#sub#Tooltip showing a disconnection due to an incompatible version{288x221}](/images/docs/static/mockoon-cloud/data-synchronization-team-collaboration/offline-reason-incompatible-version.png)
![#sub#Tooltip showing a disconnection due to an incompatible version{288x221}](docs-img:offline-reason-incompatible-version.png)

## Major versions migrations

Expand Down
42 changes: 42 additions & 0 deletions content/docs/latest/mockoon-data-files/data-files-location.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: Data files
meta:
title: Data files
description: Learn where Mockoon's data storage files and application settings are located and how to move them to other folders
order: 1100
---

# Data files

---

Mockoon desktop stores each mock API's data in a separate file. These files contain all the information about the environment, routes, and responses. They are stored in a JSON format and can be easily [shared](docs:mockoon-data-files/sharing-mock-api-files) with other Mockoon users, [used with the CLI](https://github.com/mockoon/mockoon/blob/main/packages/cli/README.md#use-your-mockoon-environment-file), or stored in a git repository.

## Data files schema

Each environment file contains information about the environment, routes, and responses. They are stored in a JSON format following a schema and are validated every time you open an environment. This schema is available in the [repository](https://github.com/mockoon/mockoon/blob/main/packages/commons/src/constants/environment-schema.constants.ts).

## Locating the mock API files

You can locate the folder in which the API data are stored by right-clicking on each environment and selecting **"Show data file in explorer/finder"**:

![click on show in folder in the context menu{551x380}](docs-img:environment-show-in-folder.png)

## Moving the files

You can move the data files to another folder by right-clicking on an environment and selecting **"Move data file to folder"**:

![click on Move data file to folder in folder in the context menu{551x411}](docs-img:environment-move-to-folder.png)

> 💡 Please note that the environment file will be copied to the new folder, and the original file will **not** be deleted. If you want to delete the original file, you will have to do it manually.
## Enabling data file watching

Mockoon can monitor data files' external changes and automatically reload the interface with the new information. This is particularly useful when you are editing the data files with an external editor or pulling changes from a git repository. You can activate this option in the settings:

![enable file monitoring in the settings{860x812}](docs-img:enable-file-watching.png)

## Cloud environments

If you are a Mockoon Cloud user, you can also create cloud environments that are stored in the cloud and synchronized across all your devices. It also allows you to collaborate in real-time with your team members.
You can learn more about this feature in the [dedicated documentation](/docs/latest/mockoon-cloud/data-synchronization-team-collaboration/).
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ order: 1130

---

Depending on your operating system, Mockoon's settings and log files are located in different folders.
Depending on your operating system, Mockoon's desktop application settings and log files are located in different folders.

## Application settings

Expand Down
Loading

0 comments on commit 36110e5

Please sign in to comment.