feat: add dart middleware to api docs

docs/apis.mdx

@@ -674,7 +674,16 @@ func validate(next apis.Handler) apis.Handler {
 ```
 
 ```dart !!
-// Middleware currently not supported in dart
+Future<HttpContext> validate(HttpContext ctx) async {
+  if (!ctx.req.headers.containsKey("Content-Type")) {
+    ctx.res.status = 400;
+    ctx.res.body = "header Content-Type is required";
+
+    return ctx;
+  }
+
+  return ctx.next();
+}
 ```
 
 </CodeSwitcher>
@@ -742,7 +751,15 @@ func main() {
 ```
 
 ```dart !!
-// API level middleware currently not supported in dart
+import 'package:nitric_sdk/nitric.dart';
+import '../middlewares';
+
+final customersApi = Nitric.api(
+  "customers",
+  opts: ApiOptions(
+    middlewares: [logRequest, validate],
+  )
+);
 ```
 
 </CodeSwitcher>
@@ -819,7 +836,21 @@ func main() {
 ```
 
 ```dart !!
-// Route level middleware currently not supported in dart
+import 'package:nitric_sdk/nitric.dart';
+import '../middlewares';
+
+Future<HttpContext> getAllCustomers(HttpContext ctx) async {
+  // gets the customers
+  return ctx.next();
+}
+
+final customersApi = Nitric.api("customers");
+
+// Inline using .get()
+customersApi.get("/customers", getAllCustomers, middlewares: [logRequest, validate]);
+
+// Inline using .route()
+customersApi.route("/customers", middlewares: [logRequest, validate]).get(getAllCustomers);
 ```
 
 </CodeSwitcher>

docs/reference/dart/api/api-all.mdx

@@ -0,0 +1,121 @@
+---
+description: "Reference for Nitric's Dart library - Register a single handler for all HTTP Methods (GET, POST, PUT, DELETE, PATCH) on the route."
+---
+
+# Dart - api.all()
+
+Register a single handler for all HTTP Methods (GET, POST, PUT, DELETE, PATCH) on a route.
+
+<Note>
+  This method is a convenient short version of
+  [api().route().all()](./api-route-all)
+</Note>
+
+```dart
+import 'package:nitric_sdk/nitric.dart';
+
+// Create an API named 'public'
+final api = Nitric.api("public");
+
+api.all("/customers/:customersId", (ctx) async {
+  // construct a response for all incoming HTTP requests
+  final responseBody = {};
+  ctx.res.json(responseBody);
+
+  return ctx;
+});
+```
+
+## Parameters
+
+<Properties>
+  <Property name="match" required type="String">
+    The path matcher to use for the route. Matchers accept path parameters in
+    the form of a colon prefixed string. The string provided will be used as
+    that path parameter's name when calling handlers.
+  </Property>
+  <Property name="handler" required type="HttpHandler">
+    The middleware service to use as the handler for HTTP requests.
+  </Property>
+  <Property name="security" type="List<OidcOptions>">
+    Security rules to apply with scopes to the entire API.
+  </Property>
+  <Property name="middlewares" type="List<HttpHandler>">
+    The list of middleware that will run before the handler is called. To call
+    the next middleware in the chain use `ctx.next()`, to finish early return
+    `ctx` by itself. The ordering of middleware goes: API -> Route -> Method.
+  </Property>
+</Properties>
+
+## Examples
+
+### Register a handler for all requests
+
+```dart
+import 'package:nitric_sdk/nitric.dart';
+
+// Create an API named 'public'
+final api = Nitric.api("public");
+
+api.all("/customers/:customersId", (ctx) async {
+  // construct a response for all incoming HTTP requests
+  final responseBody = {};
+  ctx.res.json(responseBody);
+
+  return ctx;
+});
+```
+
+### Chain services as a single method handler
+
+When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using `ctx.next()`. If a middleware in the chain does not call `.next` and instead returns the base context, the call chain will end.
+
+```dart
+import 'package:nitric_sdk/nitric.dart';
+import '../middlewares';
+
+Future<HttpContext> validate(HttpContext ctx) async {
+  if (!ctx.req.headers.containsKey("Content-Type")) {
+    ctx.res.status = 400;
+    ctx.res.body = "header Content-Type is required";
+
+    // End the middleware chain by not calling `ctx.next()`.
+    return ctx;
+  }
+
+  return ctx.next();
+}
+
+Future<HttpContext> handleCustomer(HttpContext ctx) async {
+  // handle the request...
+  return ctx.next();
+}
+
+// The validate middleware will run before the handleCustomer handler
+Nitric.api("public").all("/customers", handleCustomer, middlewares: [validate]);
+```
+
+### Access the request body
+
+The request body is accessible from the `ctx.req` object.
+
+```dart
+import 'package:nitric_sdk/nitric.dart';
+
+// Create an API named 'public'
+final api = Nitric.api("public");
+
+api.all("/customers/:customerId", (ctx) async {
+  // Extract the path parameter
+  final id = ctx.req.pathParams["customerId"]!;
+
+  // Extract the request body
+  final body = ctx.req.json();
+
+  // Construct response for the /customers request...
+  final responseBody = {};
+  ctx.res.json(responseBody);
+
+  return ctx;
+});
+```

docs/reference/dart/api/api-delete.mdx

@@ -43,6 +43,11 @@ api.delete("/customers/:customerId", (ctx) async {
   <Property name="security" type="List<OidcOptions>">
     Security rules to apply with scopes to the entire API.
   </Property>
+  <Property name="middlewares" type="List<HttpHandler>">
+    The list of middleware that will run before the handler is called. To call
+    the next middleware in the chain use `ctx.next()`, to finish early return
+    `ctx` by itself. The ordering of middleware goes: API -> Route -> Method.
+  </Property>
 </Properties>
 
 ## Examples
@@ -67,6 +72,34 @@ api.delete("/customers/:customerId", (ctx) async {
 });
 ```
 
+### Chain services as a single method handler
+
+When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using `ctx.next()`. If a middleware in the chain does not call `.next` and instead returns the base context, the call chain will end.
+
+```dart
+import 'package:nitric_sdk/nitric.dart';
+
+Future<HttpContext> validate(HttpContext ctx) async {
+  if (!ctx.req.headers.containsKey("Content-Type")) {
+    ctx.res.status = 400;
+    ctx.res.body = "header Content-Type is required";
+
+    // End the middleware chain by not calling `ctx.next()`.
+    return ctx;
+  }
+
+  return ctx.next();
+}
+
+Future<HttpContext> deleteCustomer(HttpContext ctx) async {
+  // handle the DELETE request...
+  return ctx.next();
+}
+
+// The validate middleware will run before the deleteCustomer handler
+Nitric.api("public").delete("/customers", deleteCustomer, middlewares: [validate]);
+```
+
 ### Access the request body
 
 The DELETE request body is accessible from the `ctx.req` object.

docs/reference/dart/api/api-get.mdx

@@ -43,6 +43,11 @@ api.get("/customers/:customerId", (ctx) async {
   <Property name="security" type="List<OidcOptions>">
     Security rules to apply with scopes to the entire API.
   </Property>
+  <Property name="middlewares" type="List<HttpHandler>">
+    The list of middleware that will run before the handler is called. To call
+    the next middleware in the chain use `ctx.next()`, to finish early return
+    `ctx` by itself. The ordering of middleware goes: API -> Route -> Method.
+  </Property>
 </Properties>
 
 ## Examples
@@ -63,3 +68,31 @@ api.get("/customers", (ctx) async {
   return ctx;
 });
 ```
+
+### Chain services as a single method handler
+
+When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using `ctx.next()`. If a middleware in the chain does not call `.next` and instead returns the base context, the call chain will end.
+
+```dart
+import 'package:nitric_sdk/nitric.dart';
+
+Future<HttpContext> validate(HttpContext ctx) async {
+  if (!ctx.req.headers.containsKey("Content-Type")) {
+    ctx.res.status = 400;
+    ctx.res.body = "header Content-Type is required";
+
+    // End the middleware chain by not calling `ctx.next()`.
+    return ctx;
+  }
+
+  return ctx.next();
+}
+
+Future<HttpContext> getCustomer(HttpContext ctx) async {
+  // handle the GET request...
+  return ctx.next();
+}
+
+// The validate middleware will run before the getCustomer handler
+Nitric.api("public").get("/customers", getCustomer, middlewares: [validate]);
+```

docs/reference/dart/api/api-patch.mdx

@@ -43,6 +43,11 @@ api.patch("/customers/:customerId", (ctx) async {
   <Property name="security" type="List<OidcOptions>">
     Security rules to apply with scopes to the entire API.
   </Property>
+  <Property name="middlewares" type="List<HttpHandler>">
+    The list of middleware that will run before the handler is called. To call
+    the next middleware in the chain use `ctx.next()`, to finish early return
+    `ctx` by itself. The ordering of middleware goes: API -> Route -> Method.
+  </Property>
 </Properties>
 
 ## Examples
@@ -64,6 +69,34 @@ api.patch("/customers", (ctx) async {
 });
 ```
 
+### Chain services as a single method handler
+
+When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using `ctx.next()`. If a middleware in the chain does not call `.next` and instead returns the base context, the call chain will end.
+
+```dart
+import 'package:nitric_sdk/nitric.dart';
+
+Future<HttpContext> validate(HttpContext ctx) async {
+  if (!ctx.req.headers.containsKey("Content-Type")) {
+    ctx.res.status = 400;
+    ctx.res.body = "header Content-Type is required";
+
+    // End the middleware chain by not calling `ctx.next()`.
+    return ctx;
+  }
+
+  return ctx.next();
+}
+
+Future<HttpContext> udpateCustomer(HttpContext ctx) async {
+  // handle the PATCH request...
+  return ctx.next();
+}
+
+// The validate middleware will run before the updateCustomer handler
+Nitric.api("public").patch("/customers", updateCustomer, middlewares: [validate]);
+```
+
 ### Access the request body
 
 The PATCH request body is accessible from the `ctx.req` object.

docs/reference/dart/api/api-post.mdx

@@ -43,6 +43,11 @@ api.post("/customers/:customerId", (ctx) async {
   <Property name="security" type="List<OidcOptions>">
     Security rules to apply with scopes to the entire API.
   </Property>
+  <Property name="middlewares" type="List<HttpHandler>">
+    The list of middleware that will run before the handler is called. To call
+    the next middleware in the chain use `ctx.next()`, to finish early return
+    `ctx` by itself. The ordering of middleware goes: API -> Route -> Method.
+  </Property>
 </Properties>
 
 ## Examples
@@ -64,6 +69,34 @@ api.post("/customers", (ctx) async {
 });
 ```
 
+### Chain services as a single method handler
+
+When multiple services are provided they will be called as a chain. If one succeeds, it will move on to the next. This allows middleware to be composed into more complex handlers. You can call the next middleware in the chain using `ctx.next()`. If a middleware in the chain does not call `.next` and instead returns the base context, the call chain will end.
+
+```dart
+import 'package:nitric_sdk/nitric.dart';
+
+Future<HttpContext> validate(HttpContext ctx) async {
+  if (!ctx.req.headers.containsKey("Content-Type")) {
+    ctx.res.status = 400;
+    ctx.res.body = "header Content-Type is required";
+
+    // End the middleware chain by not calling `ctx.next()`.
+    return ctx;
+  }
+
+  return ctx.next();
+}
+
+Future<HttpContext> createCustomer(HttpContext ctx) async {
+  // handle the POST request...
+  return ctx.next();
+}
+
+// The validate middleware will run before the createCustomer handler
+Nitric.api("public").post("/customers", createCustomer, middlewares: [validate]);
+```
+
 ### Access the request body
 
 The POST request body is accessible from the `ctx.req` object.