Add Callbacks, Links and Webhooks pages

.gitignore

@@ -3,3 +3,4 @@ _site/
 *.swp
 .jekyll-metadata
 .ruby-version
+.vscode

examples/tictactoe.yaml

@@ -24,9 +24,9 @@ paths:
               schema:
                 $ref: "#/components/schemas/status"
       security:
-        apiKey: []
-        app2AppOauth:
-        - board:read
+        - defaultApiKey: []
+        - app2AppOauth:
+          - board:read
 
   # Single square operations
   /board/{row}/{column}:
@@ -46,6 +46,13 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/mark"
+          links:
+            markSquare:
+              description: Operation to use if the mark value returned indicates the square is empty
+              operationId: put-square
+              parameters:
+                row: $request.path.row
+                column: $request.path.column
         "400":
           description: The provided parameters are incorrect
           content:
@@ -54,9 +61,9 @@ paths:
                 $ref: "#/components/schemas/errorMessage"
               example: "Illegal coordinates"
       security:
-        bearerHttpAuthentication: []
-        user2AppOauth:
-        - board:read
+        - bearerHttpAuthentication: []
+        - user2AppOauth:
+          - board:read
     put:
       summary: Set a single board square
       description: Places a mark on the board and retrieves the whole board and the winner (if any).
@@ -76,6 +83,13 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/status"
+        "202":
+          description: Mark operation has not completed. Use callback to check for progress
+          headers:
+            Location:
+              description: Callback URL
+              schema:
+                type: string
         "400":
           description: The provided parameters are incorrect
           content:
@@ -90,10 +104,31 @@ paths:
                 invalidMark:
                   value: "Invalid Mark (X or O)."
       security:
-        bearerHttpAuthentication: []
-        user2AppOauth:
-        - board:write
-
+        - bearerHttpAuthentication: []
+        - user2AppOauth:
+          - board:write
+      callbacks:
+        statusCallback:
+          '{$response.header.Location}':
+            get:
+              summary: Status of mark operation
+              description: Provides the status of the ongoing mark operation
+              operationId: markOperationCallback
+              responses:
+                "200":
+                  description: Mark operation has completed successfully
+                  content:
+                    application/json:
+                      schema:
+                        $ref: "#/components/schemas/status"
+                "202":
+                  description: Mark operation has not completed
+                default:
+                  description: Error returning information on mark operation progress
+                  content:
+                    application/json:
+                      schema:
+                        $ref: '#/components/schemas/errorMessage'
 components:
   parameters:
     rowParam:
@@ -179,4 +214,17 @@ components:
           scopes:
             # Reads and writes permitted via authorization code flow
             board:read: Read the board
-            board:write: Write to the board
+            board:write: Write to the board
+webhooks:
+  markStatus:
+    post:
+      summary: Status of mark operation
+      description: Provides the status of the mark operation on completion
+      operationId: markOperationWebhook
+      responses:
+        "200":
+          description: Mark operation has completed successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/status"

img/callback-object.dot

@@ -0,0 +1,77 @@
+digraph componentsObject {
+  node [shape = none; fontname = monospace; tooltip = "Click to jump to the specification of this object";];
+  rankdir = LR;
+  bgcolor = white;
+
+  openapiObject [URL = "https://spec.openapis.org/oas/v3.1.0#oasObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#94d60a"><font face="arial"><b>OpenAPI Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6ca437">openapi</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">info</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="components">components</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="security">security</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="paths">paths</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">…</td></tr></table>>;];
+
+  componentsObject [URL = "https://spec.openapis.org/oas/v3.1.0#componentsObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#94d60a" port="header"><font face="arial"><b>Components Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="callbacks">callbacks</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">…</td></tr></table>>;];
+
+  pathsObject [URL = "https://spec.openapis.org/oas/v3.1.0#pathsObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#939598" port="header"><font face="arial"><b>Paths Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6d6e71" port="endpoint1">/endpoint1</td></tr>
+    <tr><td border="1" bgcolor="#6d6e71" port="endpoint2">/endpoint2</td></tr>
+    <tr><td border="1" bgcolor="#6d6e71" port="endpoint3">/endpoint3</td></tr>
+    <tr><td border="1" bgcolor="#6d6e71">…</td></tr></table>>;];
+
+  pathItemObject [URL = "https://spec.openapis.org/oas/v3.1.0#pathItemObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#939598" port="header"><font face="arial"><b>Path Item Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6d6e71" port="delete">delete</td></tr>
+    <tr><td border="1" bgcolor="#6d6e71" port="get">get</td></tr>
+    <tr><td border="1" bgcolor="#6d6e71" port="patch">patch</td></tr>
+    <tr><td border="1" bgcolor="#6d6e71" port="post">post</td></tr>
+    <tr><td border="1" bgcolor="#6d6e71" port="put">put</td></tr>
+    <tr><td border="1" bgcolor="#6d6e71">…</td></tr></table>>;];
+
+  operationObject [URL = "https://spec.openapis.org/oas/v3.1.0#operationObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#94d60a" port="header"><font face="arial"><b>Operation Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="callbacks">callbacks</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">…</td></tr></table>>;];
+
+
+  callbackPathItemObject [URL = "https://spec.openapis.org/oas/v3.1.0#pathItemObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#94d60a" port="header"><font face="arial"><b>Path Item Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="delete">delete</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="get">get</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="patch">patch</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="post">post</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="put">put</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">…</td></tr></table>>;];
+
+
+  callbackObject [URL = "https://spec.openapis.org/oas/v3.1.0#callbackObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#94d60a" port="header"><font face="arial"><b>Callback Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="expression">{expression}</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">…</td></tr></table>>;];
+
+  openapiObject:components -> componentsObject:header;
+
+  componentsObject:callbacks -> callbackObject:header;
+
+  openapiObject:paths -> pathsObject:header;
+
+  pathsObject:endpoint1 -> pathItemObject:header;
+  pathsObject:endpoint2 -> pathItemObject:header;
+  pathsObject:endpoint3 -> pathItemObject:header;
+
+  pathItemObject:delete -> operationObject:header;
+  pathItemObject:get -> operationObject:header;
+  pathItemObject:patch -> operationObject:header;
+  pathItemObject:post -> operationObject:header;
+  pathItemObject:put -> operationObject:header;
+
+  operationObject:callbacks -> callbackObject:header;
+
+
+  callbackObject:expression -> callbackPathItemObject:header;
+}