feat: improve escape hatches (#326)

- improves the escape hatches to support skipping response processing by
returning the `SkipResponse` symbol, allowing the method handler
implementations to directly send responses. This allows for scenarios
like returning binary data that isn't currently supported by the code
generation
- refactors the e2e tests in anticipation of multiple server
implementations, and adds a few tests
- adds documentation around the included escape hatches

Author: mnahkies

e2e/openapi.yaml

@@ -5,6 +5,7 @@ info:
 tags:
   - name: request headers
   - name: validation
+  - name: escape hatches
 servers:
   - url: '{protocol}://{host}:{port}'
     variables:
@@ -91,6 +92,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Enumerations'
+  /responses/500:
+    get:
+      tags:
+      - validation
+      responses:
+        500:
+          description: Internal Server Error
+  /escape-hatches/plain-text:
+    get:
+      tags:
+        - escape hatches
+      responses:
+        200:
+          description: 'ok'
+          content:
+            text/plain:
+              schema:
+                type: string
   /responses/empty:
     get:
       tags:

e2e/scripts/generate.sh

@@ -1,20 +1,22 @@
 #!/usr/bin/env bash
 
-echo $PWD
+set -e
+
+SCHEMA_BUILDER=zod
 
 yarn openapi-code-generator \
   --input ./openapi.yaml \
-  --output ./src/generated \
+  --output ./src/generated/server/koa \
   --template typescript-koa \
-  --schema-builder zod \
+  --schema-builder "$SCHEMA_BUILDER" \
   --extract-inline-schemas \
   --grouping-strategy first-tag
 
 yarn openapi-code-generator \
   --input ./openapi.yaml \
   --output ./src/generated/client/fetch \
   --template typescript-fetch \
-  --schema-builder zod \
+  --schema-builder "$SCHEMA_BUILDER" \
   --extract-inline-schemas \
   --enable-runtime-response-validation \
   --override-specification-title "E2E Test Client"
@@ -23,7 +25,7 @@ yarn openapi-code-generator \
   --input ./openapi.yaml \
   --output ./src/generated/client/axios \
   --template typescript-axios \
-  --schema-builder zod \
+  --schema-builder "$SCHEMA_BUILDER" \
   --extract-inline-schemas \
   --enable-runtime-response-validation \
   --override-specification-title "E2E Test Client"