more bump context for design first

src/_guides/openapi/code-first-rails.md

@@ -1,7 +1,7 @@
 ---
 title: Generating OpenAPI docs for Ruby on Rails with RSwag
 authors: phil
-excerpt: This guide describes, in a code-first approach and RoR codebase, how to generate OpenAPI definition files, enhancing it with contextual information and deploying it to Bump.sh.
+excerpt: This guide describes, in a code-first approach and RoR codebase, how to generate OpenAPI description documents, enhancing it with contextual information and deploying it to Bump.sh.
 ---
 
 API Code-first is the art of building an API, and then popping some annotations or metadata in there to output API documentation in an API description format like [OpenAPI](https://spec.openapis.org/oas/latest.html).

src/_guides/openapi/code-first.md

@@ -117,9 +117,9 @@ There are not as many tools that work this way, but this is likely to be a trend
 Just like annotations you can usually run a command to extract the OpenAPI document, or you can run the web server and pull it down over HTTP.
 
 ```bash
-$ go run .
+go run .
 
-$ bump deploy http://127.0.0.1:8888/openapi.yaml \
+bump deploy http://127.0.0.1:8888/openapi.yaml \
   --doc my-documentation-name \
   --token my-documentation-token
 ```

src/_guides/openapi/design-first-rails.md

@@ -6,16 +6,24 @@ excerpt: In a Design-first approach and RoR API, leverage OpenAPI to verify spec
 
 Ruby on Rails developers are blessed with a bunch of great [OpenAPI](https://spec.openapis.org/oas/latest.html) tooling, and can use either of the API Code-First workflow which was popular for a long time, or the follow the newer API Design-first workflow. 
 
-Instead of writing loads of code and sprinkling in some metadata later to create docs, the design-first workflow assumes you create the OpenAPI descriptions before writing any code at all. Once you have the OpenAPI description documents saved in your repository, you can leverage it at every step of the API lifecycle, producing mock APIs for clients to test assumptions with, produce client libraries without writing any code, make really effective contract testing, even generate backend code to get the application teams started once the contract is all signed off.
+Instead of writing loads of code and sprinkling in some metadata later to create docs, the design-first workflow assumes you create the OpenAPI descriptions before writing any code at all. Once you have the OpenAPI description documents saved in your repository, you can leverage it at every step of the API lifecycle, to produce mock APIs for clients to test assumptions with, build client libraries without writing any code, make really effective contract testing, and even generate backend code to get the application teams started once the contract is all signed off.
 
-This guide is going to look at two specific parts of the API design-first workflow and help you get them set up in Rails.
+This guide is going to look at two specific parts of the API design-first workflow that are most helpful to documentation, and show how to set it up in Rails: request validation automatically, and contract testing responses.
+)
+- [Getting OpenAPI \& Bump.sh Setup](#getting-openapi--bumpsh-setup)
+- [Request Validation powered by OpenAPI](#request-validation-powered-by-openapi)
+- [Contract Testing with OpenAPI](#contract-testing-with-openapi)
+- [Sample Code](#sample-code)
 
-1. Request Validation with OpenAPI
-2. Contract Testing in RSpec with OpenAPI
+## Getting OpenAPI & Bump.sh Setup
 
-Once you've defined your OpenAPI via [graphical editors](https://openapi.tools/#gui-editors), [text editors](https://openapi.tools/#text-editors), or [traffic sniffing](/guides/openapi/code-first/#traffic-sniffing), you can pop it into your Git repository somewhere like `api/openapi.yaml`. 
+The API design-first workflow means you'll need to create your OpenAPI description before you start writing all your code, so if you don't have an `openapi.yaml` already that is probably the first step. You can use a wide variety of [graphical editors](https://openapi.tools/#gui-editors), [text editors](https://openapi.tools/#text-editors), or [traffic sniffing](/guides/openapi/code-first/#traffic-sniffing) to generate this OpenAPI, and there is lots of documentation and guides to help you. 
 
-Having this raw OpenAPI in your repository means that Bump.sh setup can actually come first, as there is no generation step with API Design first. To set up deployments to Bump.sh you can use the [CLI](https://github.com/bump-sh/cli#bump-deploy-file), [GitHub Actions](https://github.com/marketplace/actions/bump-sh#diff-on-pull-requests-only), or other [Continuous Integration](https://docs.bump.sh/help/continuous-integration/). Then as you progress through this guide implementing validation and contract testing, you will probaby notice mistakes in your OpenAPI, and they can be deployed with each commit/merge.
+Alternatively you can grab some sample OpenAPI from the API Guru Marketplace, and click JSON or YAML to download their OpenAPI descriptions.
+
+Either way, one you have some an OpenAPI description document, pop it into your Git repository somewhere like `api/openapi.yaml`. 
+
+Building an API for a bunch of clients is always a tricky one, but by deploying the documentation first you can see if people like the look of the API before you waste a bunch of time building it. Then as you progress through, especially if you are adding these tools to an existing codebase, you will continue to find mistakes in your OpenAPI or your actual API code, improving both as you go until you have a perfect match that will never again be broken, solving the "docs vs code" drift problem, and every fix will be deployed to Bump with each commit/merge.
 
 ```bash
 $ bump deploy api/openapi.yaml \
@@ -25,11 +33,13 @@ $ bump deploy api/openapi.yaml \
 * Your new documentation version will soon be ready at https://bump.sh/philsturgeon/doc/rails-design-first
 ```
 
-Once Bump.sh is hooked up, let's look at improving your Rails API to make it understand OpenAPI.
+Instead of using the [CLI](https://github.com/bump-sh/cli#bump-deploy-file) you could use [GitHub Actions](https://github.com/marketplace/actions/bump-sh), or a bunch of other [Continuous Integration](https://docs.bump.sh/help/continuous-integration/). 
+
+Once Bump.sh is hooked up, let's look at how we'd teach a Rails API (new, or existing) to be able to handle request validation for us.
 
-### Request Validation powered by OpenAPI
+## Request Validation powered by OpenAPI
 
-Instead of wasting loads of time writing out validation logic in dry or whatever other DSL, why not just point it at an existing OpenAPI description document and skip repeating yourself.
+Instead of wasting loads of time writing out validation logic in dry or whatever other DSL, why not just point it at an existing OpenAPI description document and skip repeating yourself? You don't need to spend forever writing out that name is required, email is also required and an email address, date of birth is a date and optional... that's what your OpenAPI description already says, and because it's in a machine readable format you can just use it as code.
 
 1. Add the [openapi_first](https://rubygems.org/gems/openapi_first) gems to your `Gemfile`.
 
@@ -69,7 +79,7 @@ Instead of wasting loads of time writing out validation logic in dry or whatever
   $ rails s
   ```
 
-5. Now using your favourite HTTP client you can try interacting with your API, to see how it works. Presuming you've got an endpoint with some require properties you can try sending a request that misses one, as a quick test to make sure it's hooked up properly: 
+1. Now using your favourite HTTP client you can try interacting with your API, to see how it works. Presuming you've got an endpoint, if not quickly make some sample controller (or grab ours from the [sample code](https://github.com/philsturgeon/rails-design-first)) and make sure the model has some required properties. A basic test is to try sending a request that misses out a required property, to see if that allows the request through or fails it.
 
   ```
   $ curl -X POST http://localhost:3000/widgets -H "Content-Type: application/json" -d '{}'  | jq .
@@ -87,7 +97,7 @@ Instead of wasting loads of time writing out validation logic in dry or whatever
   }
   ```
 
-This error is letting me know I missed the  `name` property out of my request. By default these errors are in the format defined by [RFC 9457: Problem Details for HTTP APIs](https://datatracker.ietf.org/doc/html/rfc9457), which is not just a good error format, but it means that various other tools you use throughout your stack can all be in the same format easily.
+This error is letting me know I missed the `name` property out of my request. By default these errors are in the format defined by [RFC 9457: Problem Details for HTTP APIs](https://datatracker.ietf.org/doc/html/rfc9457), which is not just a good error format, but it means that various other tools you use throughout your stack can all be in the same format easily.
 
 Anyway, if we try with a valid request now the OpenAPI middleware should let the request through, and the API should respond with a success.
 
@@ -106,7 +116,7 @@ Success! Now, without needing to write any Ruby code at all, your API is rejecti
 
 So long as you keep deploying OpenAPI changes to Bump using the CLI or GitHub Actions, now that your code is powered by your API it's impossible to have any OpenAPI drift in your requests. Responses however, they still need to be checked, and we can do that with a regular test suite that you may well have already.
 
-### Contract Testing with OpenAPI in Rails
+## Contract Testing with OpenAPI
 
 It can also power contract testing in your existing test suite, and [openapi_contracts](https://rubygems.org/gems/openapi_contracts) can help out.
 
@@ -179,7 +189,7 @@ It can also power contract testing in your existing test suite, and [openapi_con
 
   ```
 
-### Sample Code
+## Sample Code
 
 The sample code for this design first guide is published on GitHub, so please
 take a look at