diff --git a/articles/modeling/crud-builder.md b/articles/modeling/crud-builder.md index befe4d0..b9649f3 100644 --- a/articles/modeling/crud-builder.md +++ b/articles/modeling/crud-builder.md @@ -26,7 +26,7 @@ shared responses. ## Using the Editor - +![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1521751297046) We created the CRUD builder editor to make data structure creation as simple as possible. You can find the CRUD builder editor under the **Editor** tab under @@ -87,7 +87,7 @@ If you have a pre-existing JSON document that you would like to convert to a Stoplight data structure, the **Generate from JSON** button available towards the top of the CRUD editor allows you to do just that. - +![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1521751321588) To start: @@ -107,7 +107,7 @@ bodies, and shared responses. ## Editing the Raw JSON Schema - +![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1521751310398) While not for the faint hearted, you can also edit the raw JSON schema directly if you are familiar with the format, or have a pre-existing JSON schema diff --git a/articles/modeling/object-inheritance.md b/articles/modeling/object-inheritance.md index 0c88193..9ecc49e 100644 --- a/articles/modeling/object-inheritance.md +++ b/articles/modeling/object-inheritance.md @@ -42,6 +42,10 @@ different types of vehicles. To begin working on the API, you will need a base "car" model with a few attributes that are common across all vehicles. This might look similar to: +![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1521752009372) + +The JSON schema will be: + ```javascript // the car base type { @@ -67,12 +71,14 @@ might look similar to: } ``` - - Now that we have a base type model, we now need a derived type that extends the base type. Since we're dealing with cars, let's create a model that defines a SUV type (or a Sport Utility Vehicle): +![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1521751959590) + +The JSON schema will be: + ```javascript // the SUV model { @@ -99,8 +105,6 @@ SUV type (or a Sport Utility Vehicle): } ``` - - As shown above, by wrapping our SUV model inside of an `allOf` block, we are able to include all of the properties that are included in the car base model above. @@ -108,6 +112,10 @@ above. When fully de-referenced (the car reference is replaced with the car properties), the derived SUV model will have the following JSON properties: +![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1521752155156) + +The JSON schema will be: + ```javascript { "type": "object", @@ -139,9 +147,12 @@ properties), the derived SUV model will have the following JSON properties: } } ``` + --- -**Related Articles** -- [JSON Introduction](/modeling/json-best-practices/introduction) -- [Adding Validations](/modeling/json-best-practices/adding-validations) -- [Reducing Duplication with $refs](/modeling/json-best-practices/reducing-duplication-with-refs) -- [Generating Schemas](/modeling/json-best-practices/generating-schemas) + +**Related Articles** + +* [JSON Introduction](/modeling/json-best-practices/introduction) +* [Adding Validations](/modeling/json-best-practices/adding-validations) +* [Reducing Duplication with $refs](/modeling/json-best-practices/reducing-duplication-with-refs) +* [Generating Schemas](/modeling/json-best-practices/generating-schemas) diff --git a/articles/testing/variables-context.md b/articles/testing/variables-context.md index ec0d678..bf2f5cd 100644 --- a/articles/testing/variables-context.md +++ b/articles/testing/variables-context.md @@ -1,8 +1,6 @@ # Using Context Variables - - -Context variables allow you to dynamically store and share data between steps in a scenario. Contrary to environment variables, context variables are _not_ saved once a test has completed. Therefore, context variables are only suitable for temporary data. +Context variables allow you to dynamically store and share data between steps in a scenario. Contrary to environment variables, context variables are _not_ saved once a test has completed. Therefore, context variables are only suitable for temporary data. Context variables are scoped to the scenario, _not_ the collection. This means that two scenarios can both read/write the same context variable `myVar`, and not conflict with each other. Environment variables, on the other hand, are shared amongst all scenarios, and are scoped to the collection. @@ -12,9 +10,9 @@ At the start of a test run, the context object is empty. Good examples of data t Context variables make it possible to chain related steps together. For example, say we have the following set of actions to perform: -1. Create User, `POST /users`. Returns a new user object, with an `id` property. -2. Get User, `GET /users/{$.ctx.userId}`. -3. Delete User, `DELETE /users/{$.ctx.userId}`. +1. Create User, `POST /users`. Returns a new user object, with an `id` property. +2. Get User, `GET /users/{$.ctx.userId}`. +3. Delete User, `DELETE /users/{$.ctx.userId}`. Somehow we need to use the `id` property for the user created in step #1 to build the request in steps #2 and #3. This is a great case for context variables, since the data is temporary (the new user's id changes every test run, and is only needed in this single scenario). @@ -24,16 +22,14 @@ To accomplish this, we would capture/set the `$.ctx.userId` property to `output. ### With Captures - - The capture UI in the step editor makes it easy to set `$.ctx` values. You can use values from the step output or input, including headers, response bodies, etc. +![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1521752669324) + > Multiple captures can be applied to the same step, to set multiple `$.ctx` values. ### With Scripting - - Scripting allows you to use more complicated logic in a scenario step. Scripts are executed either before or after a step request finishes. Scripts are plain Javascript and give you direct access to the scenario context through the global @@ -48,7 +44,7 @@ $.ctx.set('userId', output.body.get('id')); Where the `$.ctx.set(x, y)` function adds the data referenced in the second argument (`y`) to the context under the string value of the first argument -(`x`). +(`x`). Here is another example that just sets `myVariable` to the hardcoded value `123`: @@ -58,8 +54,6 @@ $.ctx.set('myVariable', 123); ## Using Context Variables - - To use a context variable in a scenario, use the following syntax: ``` @@ -91,10 +85,8 @@ Where the braces (`{}`) are absent, and we are using the `get()` method for retrieving the context variable under the `myVariable` key. --- + **Related Articles** -- [Using Variables Overview](/testing/using-variables/overview) -- [$$.env (Environment)](/testing/using-variables/environment) - - - +* [Using Variables Overview](/testing/using-variables/overview) +* [$$.env (Environment)](/testing/using-variables/environment) diff --git a/articles/testing/variables-environment.md b/articles/testing/variables-environment.md index 0cbb4c5..9084557 100644 --- a/articles/testing/variables-environment.md +++ b/articles/testing/variables-environment.md @@ -1,15 +1,15 @@ # Using Environment Variables - - > If you have not already done so, we recommend reviewing the -[Environments](/platform/editor-basics/environments) article before continuing. +> [Environments](/platform/editor-basics/environments) article before continuing. Environment variables in Stoplight allow you to dynamically retrieve information in a scenario from the active environment. This makes it possible to switch between different environments with ease, having variables automatically populate based on the current environment. +![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1521753220632) + ## Setting Environment Variables ### With the Editor Configuration @@ -23,8 +23,8 @@ Captures make it easy to "capture" values from your step request or result, and Say you have a scenario step that sends an HTTP request to authenticate a new user. The response from that request includes an apiKey that you want to use for other requests. You can easily save that apiKey to an environment variable, for later re-use, by adding a capture in the form `$$.env.apiKey = output.body.apiKey`. After running the step, check your current environment variables and note the newly added apiKey! > Environment variables set via captures are only added to the user's private - variables, and are not sent to Stoplight. See the [Environment - section](/platform/editor-basics/environments) for more information. +> variables, and are not sent to Stoplight. See the [Environment +> section](/platform/editor-basics/environments) for more information. ### With Scripting @@ -45,13 +45,11 @@ argument (`y`) to the environment under the string value of the first argument (`x`). > Environment variables set via script are only added to the user's private - variables, and are not sent to Stoplight. See the [Environment - section](/platform/editor-basics/environments) for more information. +> variables, and are not sent to Stoplight. See the [Environment +> section](/platform/editor-basics/environments) for more information. ## Using Environment Variables - - Use an environment variable in a scenario with the following syntax: ``` @@ -83,10 +81,11 @@ $$.env.get('myVariable'); Where the braces (`{}`) are absent, and we are using the `get()` method for retrieving the environment variable under the `myVariable` key. -*** -**Related Articles** -- [Editor Configuration](/platform/editor-basics/editor-configuration) -- [Environments](/platform/editor-basics/environments) -- [Using Variables Overview](/testing/using-variables/overview) -- [$.ctx(Context)](/testing/using-variables/context) +--- +**Related Articles** + +* [Editor Configuration](/platform/editor-basics/editor-configuration) +* [Environments](/platform/editor-basics/environments) +* [Using Variables Overview](/testing/using-variables/overview) +* [$.ctx(Context)](/testing/using-variables/context) diff --git a/assets/gifs/context-variables-captures.gif b/assets/gifs/context-variables-captures.gif new file mode 100644 index 0000000..e2d605d Binary files /dev/null and b/assets/gifs/context-variables-captures.gif differ diff --git a/assets/gifs/edit-raw-json.gif b/assets/gifs/edit-raw-json.gif new file mode 100644 index 0000000..8353abf Binary files /dev/null and b/assets/gifs/edit-raw-json.gif differ diff --git a/assets/gifs/generate-from-json.gif b/assets/gifs/generate-from-json.gif new file mode 100644 index 0000000..1eafcdb Binary files /dev/null and b/assets/gifs/generate-from-json.gif differ diff --git a/assets/gifs/using-crud-builder.gif b/assets/gifs/using-crud-builder.gif new file mode 100644 index 0000000..9617c54 Binary files /dev/null and b/assets/gifs/using-crud-builder.gif differ diff --git a/assets/gifs/variable-environments.gif b/assets/gifs/variable-environments.gif new file mode 100644 index 0000000..7f52f0e Binary files /dev/null and b/assets/gifs/variable-environments.gif differ diff --git a/assets/images/object-inheritance1.png b/assets/images/object-inheritance1.png new file mode 100644 index 0000000..d95d1bb Binary files /dev/null and b/assets/images/object-inheritance1.png differ diff --git a/assets/images/object-inheritance2.png b/assets/images/object-inheritance2.png new file mode 100644 index 0000000..78d5705 Binary files /dev/null and b/assets/images/object-inheritance2.png differ diff --git a/assets/images/object-inheritance3.png b/assets/images/object-inheritance3.png new file mode 100644 index 0000000..e046134 Binary files /dev/null and b/assets/images/object-inheritance3.png differ