docs: reduce openapi to just the essentials

1 files changed, 93 insertions, 0 deletions

diff --git a/learn/openapi/README.md b/learn/openapi/README.md
new file mode 100644
index 0000000..feedf33
--- /dev/null
+++ b/learn/openapi/README.md
@@ -0,0 +1,93 @@
+# OpenAPI
+
+[OpenAPI][1] is a document that describes an API. It contains:
+
+* at least one [paths][2] field.
+* a [components][3] field or a [webhooks][4] field.
+
+Media types should conform to [RFC-6838][5].
+HTTP Status codes should follow [RFC-7231][6] and [IANA][7].
+
+## Format
+
+The document is a JSON file called `openapi.json`.
+
+```json
+{
+  "field": [1, 2, 3]
+}
+```
+
+* field names are case sensitive
+* fields can be:
+  * Fixed fields: have a declared name
+  * Patterned fields: declare a regex pattern for the field name
+
+Data Types
+
+| type    | format   |
+| ------- | -------- |
+| integer | int32    |
+| integer | int64    |
+| number  | float    |
+| number  | double   |
+| string  | password |
+
+Description fields can be written in [CommonMark][8] markdown.
+
+Minimal example:
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "xlg API",
+    "version": "0.1.0"
+  },
+  "servers": [
+    {
+      "url": "https://dev.xlg.c0/v0",
+      "description": "dev api"
+    }
+  ],
+  "paths": {
+    "/health": {
+      "get": {
+        "responses": {
+          "200": {
+            "description": "Healthy",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "status"
+                  ],
+                  "properties": {
+                    "status": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "security": {
+    "type": "openIdConnect",
+    "openIdConnectUrl": "https://xlg.auth0.com/.well-known/openid-configuration"
+  }
+}
+```
+
+[1]: https://spec.openapis.org/oas/v3.1.0#openapi-document
+[2]: https://spec.openapis.org/oas/v3.1.0#pathsObject
+[3]: https://spec.openapis.org/oas/v3.1.0#oasComponents
+[4]: https://spec.openapis.org/oas/v3.1.0#oasWebhooks
+[5]: https://www.rfc-editor.org/rfc/rfc6838.txt
+[6]: https://www.rfc-editor.org/rfc/rfc7231.txt
+[7]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
+[8]: https://spec.commonmark.org/0.30/