Apply suggestions from code review

Co-authored-by: Paul B. <[email protected]>

src/_guides/openapi/specification/v3.1/understanding-structure/basic-structure.md

@@ -55,7 +55,7 @@ info:
     identifier: CC-BY-NC-SA-4.0
 ```
 
-It can also contain the license details of your OpenAPI (note, that's different to the license details of your API which would be licensed through source control with a `LICENSE.txt`.)
+It can also contain the license details of your OpenAPI document (note, that's different to the license details of your API which would be licensed through source control with a `LICENSE.txt`.)
 
 ### 3. Servers Object
 
@@ -94,7 +94,7 @@ The `paths` object is probably the most important section for your API. It lists
             description: Booking successful
 ```
 
-Here the `operationId` helps us spot the two different operations, and give them a unique name which can be useful for all sorts of tools. The summary then gives a human readable title that will often be used in documentation tools.
+Here the `operationId` helps us spot the two different operations, and give them a unique name which can be useful for all sorts of tools. The `summary` gives a human readable title that will often be used in documentation tools.
 
 Any HTTP request which has a body (e.g.: `POST`, `PUT`, `PATCH`) can define a `requestBody`, and the responses are broken down by status code. This is a bit of a skeleton at the moment and ignores the media types and payloads. 
 
@@ -136,7 +136,6 @@ Components can also contain reusable parameters, request bodies, responses, and
 
 ```yaml
 components:
-
   requestBodies:
     TripRequest:
       description: A request body for creating a new trip.
@@ -198,7 +197,7 @@ This is just a few examples of various types of security schemes that can be def
 
 ### 6. Security Object
 
-The top-level `security` object specifies the security schemes that apply globally to the API, so if an entire API uses an API key or OAuth2 you might have:
+The top-level `security` list specifies the security schemes that apply globally to the API, so if an entire API uses an API key or OAuth2 you might have:
 
 ```yaml
 security:

src/_guides/openapi/specification/v3.1/understanding-structure/components.md

@@ -48,9 +48,6 @@ components:
       bearerFormat: JWT
 ```
 
-The full list of objects which can be defined in components is: 
-The Components object in OpenAPI allows you to create reusable bits of OpenAPI that can then be pieced together like Lego to build a better API description. This keeps things nice and tidy, and you can even spread them across multiple documents to share components between multiple APIs, or at least just keep your file sizes down.
-
 The full list of objects which can be defined in components is:
 
 - `callbacks` - Define callback objects that send outgoing requests.

src/_guides/openapi/specification/v3.1/understanding-structure/http-requests.md

@@ -5,7 +5,7 @@ excerpt: Define HTTP requests in your OpenAPI to help users know the rules on wh
 date: 2024-07-09
 ---
 
-Any API handling use-cases more advanced that purely fetching data will need to define a HTTP request body. `POST`, `PATCH`, `PUT`, all allow a HTTP client to send a body: often JSON or XML. This allows more information can be sent than just query parameters, which have limits. 
+Any API handling use-cases more advanced that purely fetching data will need to define a HTTP request body. `POST`, `PATCH`, `PUT`, all allow a HTTP client to send a body: often JSON or XML. This allows for more information to be sent rather than just query parameters, which have limits. 
 
 The request body can be used for:
 
@@ -63,11 +63,11 @@ Here the `requestBody` object defines two important properties:
 
 - `content` - specifies that the request body should be in `application/json` format with the following `schema`.
 
-The schema defines the structure of the request body, including properties like passenger_name, train_id, `date`, and `seat_preference`. This can be defined inline like this example, or it can use `components` to share an [existing schema](../data-models/schema-and-data-types.md) and reduce repetition. 
+The schema defines the structure of the request body, including properties like `passenger_name`, `train_id`, `date`, and `seat_preference`. This can be defined inline like this example, or it can use `components` to share an [existing schema](../data-models/schema-and-data-types.md) and reduce repetition. 
 
 ### Updating a Resource
 
-If a user wants to update their booking (e.g.: change the seat preference), the API can define a PUT or PATCH response, to allow updating the entire booking, or part of the booking. Either way, they need to send the updated data in the request body. Here’s how to define it:
+If a user wants to update their booking (e.g.: change the seat preference), the API can define a PUT or PATCH response, to allow updating the entire booking, or part of the booking  respectively. Either way, they need to send the updated data in the request body. Here’s how to define it:
 
 ```yaml
 paths:
@@ -94,7 +94,7 @@ paths:
                   example: "aisle"
 ```
 
-Here the `PATCH` method is used to update the one specific field that needs updating in the existing booking. The `required: true` says the `requestBody` is mandatory, and the only media type defined is `application/json` so that says the request must be in that format.
+Here the `PATCH` method is used to describe an operation that can update one specific field from an existing booking. The `required: true` says the `requestBody` is mandatory, and the only media type defined is `application/json` so that says the request must be in that format.
 
 The `schema` then defines the structure of the request body, which demonstrates that only the `seat_preference` property can be updated.