WIP OpenAPI

Author: CharlieDigital

docs/pages/how-to/openapi-bindings.md

@@ -1,3 +1,27 @@
-# How to Interacts with the Backend API
+# How to Interact with the Backend API
+
+If you're building a **Serious Backend™**, chances are that you're going to need an OpenAPI specification as an output for a number of reasons.
+
+First is typically to generate the client TypeScript bindings.  Yes, even if you're using TypeScript on the backend, this makes sense because the frontend model is typically only a subset oF the backend model and the OpenAPI interface is the boundary between front- and back-ends.
+
+Second is that many platforms like [AWS API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-open-api.html) and [Google Cloud API Gateway](https://cloud.google.com/api-gateway/docs/openapi-overview) consume OpenAPI specs.  If you are building an enterprise API or any sort of API where you'll want to implement an API gateway, you'll want OpenAPI.  So even if your frontend is a TypeScript React, Vue, or Svelte application, it makes sense to use the OpenAPI bindings to generate the clients if an API gateway is in the system design.
+
+Third is that OpenAPI can be the foundation of your externally facing APIs and documentation generation using tools like [Redocly](https://redocly.com/) and [Mintlify](https://mintlify.com/docs/api-playground/openapi/setup).  If you're just building a simple, self-contained web app, then it isn't relevant.  But if you're building a serious product (probably why you're using Nest.js and curious about .NET), then OpenAPI tooling is key.
+
+::: info .NET OpenAPI support
+Depending on which style of API is used (Minimal, FastEndpoints, or Controllers), the approach to annotating files changes with C# and .NET.  In this guide, we'll walk through the setup of controller APIs as these are the closest match for Nest.js.
+
+Additionally, with .NET 9, Microsoft now offers first party tooling to support exporting OpenAPI specifications though the support for controllers has some gaps around the XML code comments at the moment.
+:::
+
+## Authoring
+
+🚧 WIP
+
+## Generating Spec Files
+
+🚧 WIP
+
+## Generating Client Bindings
 
 🚧 WIP

docs/pages/intermediate/express-vs-minimal-api.md

@@ -4,6 +4,10 @@ Both **Express.js** and **.NET Minimal Web APIs** provide lightweight ways to bu
 
 **.NET Minimal Web APIs**, introduced in .NET 6, offer a streamlined way to build APIs with high performance and **built-in production-ready features** (no hunting for NPM packages!). Unlike Express, .NET Minimal APIs leverage the highly optimized ASP.NET Core pipeline, benefiting from asynchronous request handling, automatic dependency injection, and built-in middleware for logging, authentication, and rate limiting—many of which only need to be progressively enabled and configured rather than installed separately.
 
+::: tip
+For something between .NET Minimal APIs and .NET Controller APIs, check out [FastEndpoints](https://fast-endpoints.com/) which offers performance comparable to .NET Minimal APIs while offering a better way to organize endpoints into single responsibility files/classes.
+:::
+
 ## Setting Up
 
 We'll follow [this guide](https://blog.logrocket.com/how-to-set-up-node-typescript-express/) to set up Express with TypeScript

docs/pages/intro-and-motivation.md

@@ -12,8 +12,8 @@ This guide aims to provide a walkthrough of just how similar these two languages
 Many of the code examples in this guide are actually in [the GitHub repo](https://github.com/CharlieDigital/typescript-is-like-csharp).  Be sure to check it out so you can see the full examples and play around with the code yourself.
 :::
 
-::: info
-This guide was inspired by the [Kotlin is Like C#](https://ttu.github.io/kotlin-is-like-csharp/) guide I came across while learning Kotlin.
+::: info Inspired by...
+This guide was inspired by the [Kotlin is Like C#](https://ttu.github.io/kotlin-is-like-csharp/) guide I came across while learning Kotlin.  I liked the format and decided to take it to the next level!
 :::
 
 ## Are They *Really* Similar?
@@ -290,7 +290,7 @@ It will also accept this:
 
 And now the `createCatDto` is carrying an extra `bark` property of dubious content because JavaScript doesn't care!  *TypeScript's type safety means nothing at runtime.*
 
-That's because the type information no longer exists at runtime and there's no enforcement of type which requires adding schema validators like [Zod](https://zod.dev/) or [Valibot](https://valibot.dev/) to actually check the incoming payload conforms to some shape.  Of course we can add validations and schemas to prevent a `CreateCatDTO` from accepting a `CreateDogDTO` at runtime, but this is ***extra work.***  (In fact, you might be here exactly because you're fed up with this extra work to ensure the correctness and safety of your backend application!)
+That's because the type information no longer exists at runtime and there's no enforcement of type which requires adding schema validators like [Zod](https://zod.dev/) or [Valibot](https://valibot.dev/) to actually check the incoming payload conforms to some shape.  Of course we can add validations and schemas to prevent a `CreateCatDto` from accepting a `CreateDogDto` at runtime, but this is ***extra work.***  (In fact, you might be here exactly because you're fed up with this extra work to ensure the correctness and safety of your backend application!)
 
 ::: tip If you are already using Nest.js...
 Then you will probably like [.NET controller web APIs](./intermediate/nest-vs-controller-api.md) which is conceptually similar with controllers, routes, middleware, and more.