From 4fdb7ea483b80e01bf9d2eab8364e87a5ead4359 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Fri, 2 Feb 2018 15:20:45 -0600 Subject: [PATCH 1/4] Update environments --- articles/editor/environments.md | 49 +++++++++++++++++++++++++-------- 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/articles/editor/environments.md b/articles/editor/environments.md index 5e35ff3..dbd107b 100644 --- a/articles/editor/environments.md +++ b/articles/editor/environments.md @@ -1,25 +1,50 @@ # Environments -![](../../assets/gifs/editor-configuration.gif) + -The Stoplight editor includes an embedded configuration system that can be used to auto-populate environment information and other variables (hostnames, ports, passwords, etc.) utilized by specifications, scenarios, or collections. To setup the editor configuration, click the icon towards the top right of the editor screen immediately to the left of your username. +The Stoplight editor includes an embedded configuration system that can be used +to auto-populate environment information and other variables (hostnames, ports, +passwords, etc.) utilized by specifications, scenarios, or collections. To +display the current editor environment variables, click the icon on the top +right of the Stoplight editor as shown in the image above. -![](../../assets/images/editor-configuration.png) + + +For more information on environment variables and how they can be used, please +see [here](../testing/variables-environment.md). ## Private Variables -The left-half of the configuration window is dedicated to "Private Variables", which are variables that are _only_ stored locally on your system and are never sent to Stoplight. Private Variables should be reserved for secrets specific to you, such as user-specific passwords, API keys, and other pieces of sensitive data. +Private Variables are variables that are _only_ stored locally on your system +and are never sent to Stoplight or the rest of your team. Private variables +should be reserved for secrets specific to you, such as user-specific passwords, +API keys, and other pieces of sensitive data. -## Resolved Variables +> Since private variables are only stored on your computer, make sure they are + backed up in a secure location -The right-half of the configuration window displays "Resolved Variables", which is a read-only view of the variables currently exposed to your editor based on your current environment. These variables are stored in the `.stoplight` file included in your project (under "Config" in the File Explorer). To update the default or environment-specific variables stored in Stoplight, click the "Manage Environments" button under the configuration window. +## Resolved Variables -![](../../assets/gifs/editor-configuration2.gif) +Resolved Variables shows a read-only view of the variables that are currently +exposed to your editor, based on: -Variables stored in your configuration are in JSON, and can be referenced using the following format: +* Your current environment +* Your private variables -``` -{$$.env.myVariable} -``` +These variables (excluding your private variables) are stored in the +`.stoplight` file of your project (under "Config" in the File Explorer). -Where `myVariable` is the name of the variable in your configuration. +To update the default or environment-specific variables stored in Stoplight, +click the "Manage Environments" button under the configuration window. + + + +For more information on updating and customizing environment variables, please +see [here](./editor-configuration.md#environments). + +*** + +**Results** + +* [Using Environment Variables](../testing/variables-environment.md) +* [Configuration with the `.stoplight.yml` File](./editor-configuration.md#environments) From 64a8a959217b1d629dfd5a3ea0476c476b062d66 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Fri, 2 Feb 2018 15:35:15 -0600 Subject: [PATCH 2/4] Small update to resolved variables section. --- articles/editor/environments.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/articles/editor/environments.md b/articles/editor/environments.md index dbd107b..b5eed19 100644 --- a/articles/editor/environments.md +++ b/articles/editor/environments.md @@ -34,8 +34,10 @@ exposed to your editor, based on: These variables (excluding your private variables) are stored in the `.stoplight` file of your project (under "Config" in the File Explorer). -To update the default or environment-specific variables stored in Stoplight, -click the "Manage Environments" button under the configuration window. +The Resolved Variables displayed in the editor will change depending on your +current environment. To update the default or environment-specific variables +stored in Stoplight, click the "Manage Environments" button under the +configuration window. From 59e35071b07545aaf49daa20b3c2f18a46116ce6 Mon Sep 17 00:00:00 2001 From: Robert Wallach Date: Mon, 5 Feb 2018 13:42:21 -0600 Subject: [PATCH 3/4] Update environments.md --- articles/editor/environments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/editor/environments.md b/articles/editor/environments.md index b5eed19..4930b25 100644 --- a/articles/editor/environments.md +++ b/articles/editor/environments.md @@ -26,7 +26,7 @@ API keys, and other pieces of sensitive data. ## Resolved Variables Resolved Variables shows a read-only view of the variables that are currently -exposed to your editor, based on: +exposed to your editor. They are based on: * Your current environment * Your private variables From 8785635e7cc333fb5c6e5c4f2eb6f5d977568d68 Mon Sep 17 00:00:00 2001 From: Marc MacLeod Date: Wed, 7 Feb 2018 17:12:33 -0600 Subject: [PATCH 4/4] Update environments.md add dos and donts, re-work intro a bit, indicate private are merged over default variables --- articles/editor/environments.md | 41 ++++++++++++++++----------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/articles/editor/environments.md b/articles/editor/environments.md index 4930b25..5be8849 100644 --- a/articles/editor/environments.md +++ b/articles/editor/environments.md @@ -2,44 +2,43 @@ -The Stoplight editor includes an embedded configuration system that can be used -to auto-populate environment information and other variables (hostnames, ports, -passwords, etc.) utilized by specifications, scenarios, or collections. To -display the current editor environment variables, click the icon on the top -right of the Stoplight editor as shown in the image above. +An environment is simply a container for data, represented as a list of key-value pairs (behind the scenes, this is a JSON object). Every Stoplight project has one or more environments associated with it. The data stored in an environment can be used in many places within the Stoplight editor. + +Environments, and their default data, are defined in the [Stoplight configuration file](./editor-configuration.md#environments). + +- __Do__ create an environment for each development environment associated with the project. For example, `development`, `staging`, and `production`. +- __Don't__ create environments for individual users. Instead, use private variables (below) to customize existing environments. +- __Do__ use environment default data to store shared information like hostnames, ports, passwords, etc. +- __Don't__ use environments to store fixture/seed/temporary data. -For more information on environment variables and how they can be used, please +For more information on environment variables and how they can be used during API testing, please see [here](../testing/variables-environment.md). ## Private Variables -Private Variables are variables that are _only_ stored locally on your system +Private Variables are _only_ stored locally on your system, and are never sent to Stoplight or the rest of your team. Private variables should be reserved for secrets specific to you, such as user-specific passwords, -API keys, and other pieces of sensitive data. +API keys, and other pieces of sensitive and/or individually specific data. + +Edit private variables by clicking on the environment button in the top right of the Stoplight editor. > Since private variables are only stored on your computer, make sure they are - backed up in a secure location + backed up in a secure location. ## Resolved Variables Resolved Variables shows a read-only view of the variables that are currently exposed to your editor. They are based on: -* Your current environment -* Your private variables +* The currently selected (active) environment +* The active environment's default variables, as defined in the stoplight configuration file +* The active environment's private variables, as defined by you -These variables (excluding your private variables) are stored in the -`.stoplight` file of your project (under "Config" in the File Explorer). - -The Resolved Variables displayed in the editor will change depending on your -current environment. To update the default or environment-specific variables -stored in Stoplight, click the "Manage Environments" button under the -configuration window. - - +Private variables are merged over default variables that share the same name. This makes it easy +for individual team members to customize and extend environments without affecting the rest of the team. For more information on updating and customizing environment variables, please see [here](./editor-configuration.md#environments). @@ -48,5 +47,5 @@ see [here](./editor-configuration.md#environments). **Results** -* [Using Environment Variables](../testing/variables-environment.md) +* [Using Environment Variables in Testing](../testing/variables-environment.md) * [Configuration with the `.stoplight.yml` File](./editor-configuration.md#environments)