doc: add notes on open api spec

1 files changed, 173 insertions, 0 deletions

diff --git a/doc/spec.md b/doc/spec.md
new file mode 100644
index 0000000..8f0f87f
--- /dev/null
+++ b/doc/spec.md
@@ -0,0 +1,173 @@
+## Minimal Document Structure
+
+* openapi: version of the OAS. e.g. "3.1.0"
+* info: provides metadata about the API
+* paths: describes each of the endpoints in the API
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "The API",
+    "version": "0.1.0"
+  },
+  "paths": {
+  }
+}
+```
+
+## API Endpoints (paths)
+
+* "paths": is an object with the route path as the key.
+  * http method: the http method for each path that the path responds to
+  * "responses" is an object with http status codes for each key.
+
+```json
+{
+  "paths": {
+    "/users" {
+      "get": {
+        "summary": "List all the users",
+        "description": "List all the users",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "q",
+            "schema": {
+              "type": "string",
+              "minimum": 2,
+              "maximum": 256
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "create a user",
+        "description": "create a user",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "username": "string",
+                  "email": "string"
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "204": {
+            "description": "No Content",
+          },
+        }
+      }
+    }
+  }
+}
+```
+
+## Content
+
+The `content` field in each response is an object with keys for each media type
+that the endpoint can be returned as.
+
+* "content": object with keys for each media type
+  * media type: the shape of each response for the media type
+
+```json
+{
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "array",
+        "minItems": 0,
+        "maxItems": 12,
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": "integer",
+            "username": "string",
+            "email": "string"
+          }
+        }
+      }
+    },
+    "text/html": {
+      "schema": {
+      }
+    }
+  }
+}
+```
+
+## Schema
+
+The schema object defines the shape of the response via [JSON schema][1].
+
+```json
+"schema": {
+  "type": "array",
+  "minItems": 0,
+  "maxItems": 12,
+  "items": {
+    "type": "object",
+    "properties": {
+      "id": "integer",
+      "username": "string",
+      "email": "string"
+    }
+  }
+}
+```
+
+## Parameter Object
+
+* "in": the location of the parameter
+  * "path": parameter is part of the request path
+  * "query": parameter is a query string parameter of the request
+  * "header": parameter is a header of the request.
+* "name": the name of the parameter
+
+```json
+{
+  "in": "path|query|header",
+  "name": "q"
+}
+```
+
+## Request Body Object
+
+```json
+{
+  "requestBody": {
+    "content": {
+      "application/json": {
+        "schema": {
+          "type": "object",
+          "properties": {
+            "username": "string",
+            "email": "string"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+[1]: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00