Vale

mallachari · Sep 27, 2022 · 880dce0 · 880dce0
1 parent d4a3fb4
commit 880dce0
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 29 deletions.
diff --git a/docs/getting-started/02-concepts.md b/docs/getting-started/02-concepts.md
@@ -28,7 +28,7 @@ Read more about this in the [Prism mocking guide](../guides/01-mocking.md).
 
 Mocking helps when there is no real API and helps API consumers feel confident they're 
 building applications that will work with the API. Then, when the API has been built, 
-Prism can continue to help by proxying requests to the real server and reporting if anything is different. 
+Prism can continue to help by sending proxy requests to the real server and reporting if anything is different. 
 
 Running Prism on the [CLI](./03-cli.md) with `prism proxy openapi.yml http://api.example.com/` 
 will run a HTTP server similar to the mock, and it will use the same

diff --git a/docs/getting-started/03-cli.md b/docs/getting-started/03-cli.md
@@ -142,7 +142,7 @@ The response body contains the found output violations.
 
 ### Skip Request Validation
 
-In some cases, you may want to skip request validation but validate responses. A common scenario would be where you want to check if your HTTP handlers validate the request appropriately. Prism will validate all requests by default, but you can skip this by setting the flag to `--validate-request` flag to `false`.
+Sometimes, you may want to skip request validation but validate responses. A common scenario would be where you want to check if your HTTP handlers validate the request appropriately. Prism will validate all requests by default, but you can skip this by setting the flag to `--validate-request` flag to `false`.
 
 ```bash
 prism proxy examples/petstore.oas2.yaml https://petstore.swagger.io/v2 --errors --validate-request false

diff --git a/docs/guides/01-mocking.md b/docs/guides/01-mocking.md
@@ -1,17 +1,17 @@
 # HTTP Mocking
 
-Prism's HTTP mock server simulates a real web API by providing endpoints and validation rules described in your API description document. This allows client developers to begin writing code for frontend services like web, mobile, or other backend applications, whilst the API developers are still writing their code. This can help find and solve problems early on, before the API is built, because changing all that code can be expensive (time is money).
+Prism's HTTP mock server simulates a real web API by providing endpoints and validation rules described in your API description document. This allows client developers to begin writing code for frontend services like web, mobile, or other backend applications, while API developers are still writing code. This can help find and solve problems early on, before the API is built, because changing all that code can be expensive.
 
 - Does the API contain the information the client needs?
 - Is that data in the format the client needs?
 - Are the resources too "normalized" and data-centric (instead of being use-case centric) that the client has to 3292375 calls to get all the data?
 - Is there enough time left for feedback to be implemented?
 - If the feedback spawns large enough work, will the client have time implement this API once it's done?
-- Avoid all of these problems by getting a free API to play with without spending a month building it all.
+- Avoid these problems by getting a free API to play with without spending a month building it all.
 
 Catching problems early on while you're still just tweaking the API descriptions (maybe using [Studio](https://stoplight.io/studio)), means you can avoid making costly changes to the production API, deprecating old things, or creating whole new global versions which add a huge workload to every single client.
 
-Just like HTTP messages, there are two halfs to mocking: requests and responses.
+Just like HTTP messages, there are two halves to mocking: requests and responses.
 
 - [Response Generation](#response-generation)
 - [Request Validation](#request-validation)
@@ -31,7 +31,7 @@ The response Prism decides to give can be figured out with this decision flow di
 
 ### Response Examples
 
-If a response has an example, it will be used for the response. If there are multiple examples then they can be selected by name. Let's take a look at a part of an OpenAPI description, this is an operation with a response that has a 200 OK and multiple examples:
+If a response has an example, it will be used for the response. If there are multiple examples then they can be selected by name. In the following OpenAPI description, the operation has a 200 OK response and multiple examples:
 
 ```yaml
 responses:
@@ -73,7 +73,7 @@ Calling the same URL with the `Prefer` header `example=dog` `http://127.0.0.1:40
 
 > #### Remember to provide expected response code
 >
-> It is always worth indicating the HTTP response code from which `example` should be taken. If Prism decides to change the response code due to validation or security violations, your `example` might be ignored.
+> It's always worth indicating the HTTP response code from which `example` should be taken. If Prism decides to change the response code due to validation or security violations, your `example` might be ignored.
 
 ```json
 {
@@ -97,19 +97,17 @@ If the HTTP server has been started in static mode, specific calls can be made i
 
 #### Static Response Generation
 
-If the provided OpenAPI Schema Object has a response body example, it is used to provide a response.
+If the provided OpenAPI Schema Object has a response body example, it's used to provide a response.
 
 If not, a response body will be created by looking through the whole `schema` object (following any `$ref`'s it finds along the way) to create a full fake response.
 
 - If the property has a default value, then it will return the specified value.
 - If the property has an `examples` value, then it will return the first element in the array.
-- If the property has neither an example nor a default value and is **nullable**, it will return null.
-- If the property has neither an example nor a default value and is **not** nullable, but has a `format` specified, then it will return a meaningful static value according to the format.
-- If the property has neither an example nor a default value, is not nullable, and has no `format` specified, then it will return `'string'` in case of a string and `0` in case of a number.
+- If the property has neither an example nor a default value and **is nullable**, it will return null.
+- If the property has neither an example nor a default value and **isn't nullable**, but has a `format` specified, then it will return a meaningful static value according to the format.
+- If the property has neither an example nor a default value, isn't nullable, and has no `format` specified, then it will return `'string'` in case of a string and `0` in case of a number.
 
-Let's try an example! 🐶
-
-This is a schema component found in our OpenAPI description document:
+For example, this is a schema component found in an OpenAPI description document:
 
 ```yaml
 Pet:
@@ -127,7 +125,7 @@ Pet:
         type: string
 ```
 
-When we call `curl http://127.0.0.1:4010/pets/123`, the operation references this component so we get a doggie:
+When you call `curl http://127.0.0.1:4010/pets/123`, the operation references this component and a doggie is returned:
 
 ```json
 {
@@ -137,11 +135,11 @@ When we call `curl http://127.0.0.1:4010/pets/123`, the operation references thi
 }
 ```
 
-Notice that `name` had an `example` with a value so Prism used it, but `photoUrls` did not, so it just returned `"string"`. 🤷‍♂️
+Notice that `name` had an `example` with a value so Prism used it, but `photoUrls` didn't, so it just returned `"string"`. 🤷‍♂️
 
 #### Dynamic Response Generation
 
-Testing against the exact same piece of data over and over again is not the best way to build a robust integration. What happens when a name is longer than you expected, or the value happens to be 0 instead of 6?
+Testing against the exact same piece of data over and over again isn't the best way to build a robust integration. What happens when a name is longer than you expected, or the value happens to be 0 instead of 6?
 
 Dynamic mode solves this by generating a random value for all the properties according to their type, and other information like `format` or even the all-powerful `x-faker` extension.
 
@@ -165,7 +163,7 @@ Pet:
         x-faker: image.imageUrl
 ```
 
-When we call `curl http://127.0.0.1:4010/pets/123 -H "Prefer: dynamic=true"`, the operation references this component so we get a doggie:
+Call `curl http://127.0.0.1:4010/pets/123 -H "Prefer: dynamic=true"`, the operation references this component and a doggie is returned:
 
 ```json
 {
@@ -227,13 +225,13 @@ x-json-schema-faker:
 
 ## Request Validation
 
-Having a mock server which only gave responses would not be very useful, which is why
-Prism imitates request validation too. Seeing as an OpenAPI description document is
-full of all sorts of validation rules like type, format, max length, etc., Prism can
-validate incoming messages, and provide validation feedback if people are sending invalid
-requests to it.
+Having a mock server that only gives responses would not be very useful, which is why
+Prism imitates request validation too. An OpenAPI description document is
+full of validation rules like type, format, max length, etc., Prism can
+validate incoming messages and provide validation feedback if it receives invalid
+requests.
 
-Read more about this in our [Request Validation guide](./02-request-validation.md).
+Read more about this in the [Prism Request Validation guide](./02-request-validation.md).
 
 ## Deprecating operations
 

diff --git a/docs/guides/02-request-validation.md b/docs/guides/02-request-validation.md
@@ -2,13 +2,13 @@
 
 Based on the API description document, Prism can take educated guesses at all sorts of validation rules for the request body, headers, query parameters, using keywords like `type`, `format`, `maxLength`, etc.
 
-It can also fail with `401` if security information is missing, and do a bunch of other things the API description document says the real API will do. If the folks implementing the real API do it differently to their shared documents... well you should maybe have words with them.
+It can also fail with `401` if security information is missing, and do a bunch of other things the API description document says the real API will do. 
 
 ## Parameter Validation
 
 Requests which expect a request body, query parameter, or a path parameter, will be validated.
 
-For example, let's make a POST with a JSON body which is missing the required `name` parameter. We'll be using the [petstore openapi 2 version][petstore-oas2].
+For example, make a POST with a JSON body that is missing the required `name` parameter. 
 
 ```bash
 curl -X POST -s -D "/dev/stderr" -H "content-type: application/json" -d '{"tag":"Stowford"}' http://127.0.0.1:4010/pets
@@ -18,7 +18,7 @@ In this case, Prism will:
 
 - Look for a response with status code `422` on the operation you were trying to execute.
 - If there's not a `422` defined, it will look for a response with status code `400` on the operation you were trying to execute.
-- In case there's neither a `422` nor a `400` defined, Prism will create a `422` response code for you indicating all the validation errors it found along the way. Such response will have a payload conforming the [application/problem+json][rfc7807] specification.
+- In case there's neither a `422` nor a `400` defined, Prism will create a `422` response code for you indicating the validation errors it found along the way. Such response will have a payload conforming the [application/problem+json][rfc7807] specification.
 
 To get back to our example, since the operation hasn't any error response defined, Prism will generate a 422 response:
 
@@ -55,7 +55,7 @@ Pairing a GET with a request body is another example of a `422` response you may
 
 OpenAPI allows the entire API, or certain operations, to be associated with specific servers.
 
-To make sure the server URL you plan to use is a valid server for the API, or for the particular operation you are attempting, provide it as a `__server` query param.
+To make sure the server URL you plan to use is a valid server for the API, or for the particular operation you are attempting, provide it as a `__server` query parameter.
 
 Take this minimalist OpenAPI example:
 
@@ -85,7 +85,7 @@ curl http://localhost:4010/pet?__server=https://stoplight.io/api
 hello world
 ```
 
-On the other hand, putting a server which is not defined in the specification, for example:
+On the other hand, putting a server which isn't defined in the specification:
 
 ```bash
 curl http://localhost:4010/pet?__server=https://nonsense.com/api