clean up and refactor (#32)

* Organize collection schemas into array-max-*.yaml files. I tried to name the files after the natural upper bound that they all share. This makes it clearer what the collection describes, too, besides not having to repeat the actual constant.
* Move most of the base responses into the top level openapi.yaml file. This means that all the header definitions can be references in the bundled spec which had ballooned past 12k lines. It's now down to ~4500, which is what the original unsplit spec sat at, IIRC.
* Enable redocly lint again locally on save. We can add the VS Code plugin back to populated the problems tab, but this is working for me. That linter validates examples. I deleted a couple of examples that weren't validating, but we have a lot of examples to create, so I don't think that's a problem.
* Redocly doesn't dereference externalValue examples, so I changed them to `$ref:` and put them in the `docs/examples` folder for now.
* Ensure all requests use 400 with the problem media type, and they all have an empty 500 which is used as the default response, too.
* Most importantly, all the linter builds are passing and there are no local warnings. I also did some ad hoc experimentation with Azure's `autotest` to make sure I could generate a client with it. That did uncover a few schema issues that are addressed here as well.

.devcontainer/post.sh

@@ -31,7 +31,8 @@ if [[ ("${1,,}" == "bundle") || ("${1,,}" == "start") ]]; then
     if [[ -n "$BUNDLE_PID" && -n "$(ps -p $BUNDLE_PID)" ]]; then
         kill $BUNDLE_PID
     fi
-    redocly bundle $DOCS_PATH/_data/openapi-split.yaml -o $DOCS_PATH/openapi.yaml &
+    redocly bundle $DOCS_PATH/_data/openapi-split.yaml -o $DOCS_PATH/openapi.yaml && \
+    npx @redocly/cli lint ./docs/openapi.yaml &
     export BUNDLE_PID=$!
 fi
 

.spectral.yaml

@@ -14,6 +14,14 @@ rules:
       - field: "500.content"
         function: truthy
 
+  "owasp:api3:2019-define-error-responses-500-head":
+    message: "Operation is missing {{property}}."
+    description: OWASP API Security recommends defining schemas for all responses, even errors. The 500 describes what happens when a request fails with an internal server error, so its important to define this not just for documentation, but to empower contract testing to make sure the proper JSON structure is being returned instead of leaking implementation details in backtraces.
+    given: $.paths.*[head].responses
+    then:
+      - field: "500"
+        function: truthy
+
   "owasp:api3:2019-define-error-responses-401":
     message: "Operation is missing {{property}}."
     description: "OWASP API Security recommends defining schemas for all responses, even errors. The 401 describes what happens when a request is unauthorized, so its important to define this not just for documentation, but to empower contract testing to make sure the proper JSON structure is being returned instead of leaking implementation details in backtraces."
@@ -24,6 +32,12 @@ rules:
       - field: "401.content"
         function: truthy
 
+  # we do not require content for rate limiting
+  "owasp:api4:2019-rate-limit-responses-429":
+    given: $.paths..responses
+    then:
+      - field: "429"
+        function: truthy
 
   "should-have-422":
     message: "Operation is missing {{property}}."

.vscode/settings.json

@@ -3,7 +3,7 @@
     "emeraldwalk.runonsave": {
         "commands": [
             {
-                "match": "docs/_data/*",
+                "match": "docs/*",
                 "isAsync": true,
                 "cmd": ".devcontainer/post.sh bundle"
             }

docs/_data/components/responses/read-head.yaml

@@ -0,0 +1,21 @@
+'200':
+  $ref: '../../openapi-split.yaml#/components/responses/200'
+'304':
+  $ref: '../../openapi-split.yaml#/components/responses/304'
+'400':
+  $ref: '../../openapi-split.yaml#/components/responses/400'
+'401':
+  $ref: '../../openapi-split.yaml#/components/responses/401'
+'403':
+  $ref: '../../openapi-split.yaml#/components/responses/403'
+'404':
+  $ref: '../../openapi-split.yaml#/components/responses/404'
+'406':
+  $ref: '../../openapi-split.yaml#/components/responses/406'
+'410':
+  $ref: '../../openapi-split.yaml#/components/responses/410'
+'429':
+  $ref: '../../openapi-split.yaml#/components/responses/429'
+'500': &unexpected-error
+  $ref: '../../openapi-split.yaml#/components/responses/500'
+default: *unexpected-error