Merge pull request #78 from SensibleWood/main

feat: New page for OpenAPI security features

Author: darrelmiller

.gitignore

@@ -1,3 +1,5 @@
 .jekyll-cache/
 _site/
 *.swp
+.jekyll-metadata
+.ruby-version

Gemfile.lock

@@ -77,6 +77,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-21
+  x86_64-darwin-23
   x86_64-linux
 
 DEPENDENCIES

README.md

@@ -4,8 +4,12 @@
 
 Are you new to the OpenAPI Specification?
 
-Read our [Getting started](https://learn.openapis.org/) page first.
+Read our [Getting Started](https://learn.openapis.org/) page first.
 
+<p>Original site customized based on a theme based on theme by Patrick Marsceill, distributed by an <a href="https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt">MIT license.</a></p>
 
+## Development
 
-<p>Original site customized based on a theme based on theme by Patrick Marsceill, distributed by an <a href="https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt">MIT license.</a></p>
+To run this website locally you'll need to use Jekyll.
+
+Please follow the official [Quickstart](https://jekyllrb.com/docs/) guide for more information if you are starting from scratch, and then follow the instructions in the [Contributing Guide](./CONTRIBUTING.md).

_config.yml

@@ -8,7 +8,7 @@ footer_content: "\xA9 2023 OpenAPI Initiative. <a rel=\"license\" href=\"http://
   ><img alt=\"Creative Commons License\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by/4.0/80x15.png\"\
   \ /></a><br />This work is licensed under a <a rel=\"license\" href=\"http://creativecommons.org/licenses/by/4.0/\"\
   >Creative Commons Attribution 4.0 International License</a>. The documentation is\
-  \ maintained in <a href=\"https://github.com/OAI/Documentation/\">https://github.com/OAI/Documentation/</a>."
+  \ maintained in <a href=\"https://github.com/OAI/learn.openapis.org/\">https://github.com/OAI/learn.openapis.org/</a>."
 color_scheme: oai
 highlighter: rouge
 plugins:

examples/tictactoe.yaml

@@ -23,6 +23,10 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/status"
+      security:
+        apiKey: []
+        app2AppOauth:
+        - board:read
 
   # Single square operations
   /board/{row}/{column}:
@@ -49,6 +53,10 @@ paths:
               schema:
                 $ref: "#/components/schemas/errorMessage"
               example: "Illegal coordinates"
+      security:
+        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).
@@ -81,6 +89,10 @@ paths:
                   value: "Square is not empty."
                 invalidMark:
                   value: "Invalid Mark (X or O)."
+      security:
+        bearerHttpAuthentication: []
+        user2AppOauth:
+        - board:write
 
 components:
   parameters:
@@ -135,3 +147,36 @@ components:
           $ref: "#/components/schemas/winner"
         board:
           $ref: "#/components/schemas/board"
+  securitySchemes:
+    defaultApiKey:
+      description: API key provided in console
+      type: apiKey
+      name: api-key
+      in: header
+    basicHttpAuthentication:
+      description: Basic HTTP Authentication
+      type: http
+      scheme: Basic
+    bearerHttpAuthentication:
+      description: Bearer token using a JWT
+      type: http
+      scheme: Bearer
+      bearerFormat: JWT
+    app2AppOauth:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://learn.openapis.org/oauth/2.0/token
+          scopes:
+            # Only reading the board allow with delegated access
+            board:read: Read the board
+    user2AppOauth:
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://learn.openapis.org/oauth/2.0/auth
+          tokenUrl: https://learn.openapis.org/oauth/2.0/token
+          scopes:
+            # Reads and writes permitted via authorization code flow
+            board:read: Read the board
+            board:write: Write to the board

img/security-object.dot

@@ -0,0 +1,110 @@
+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>>;];
+  
+  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="security">security</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">…</td></tr></table>>;];
+  
+  securityRequirementObject [URL = "https://spec.openapis.org/oas/v3.1.0#securityRequirementObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#94d60a" port="header"><font face="arial"><b>Security Requirement Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="name">name</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="schemas">schemas</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="responses">responses</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="parameters">parameters</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="securitySchemes">securitySchemes</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">…</td></tr></table>>;];
+  
+  securitySchemesMap [URL = "https://spec.openapis.org/oas/v3.1.0#securitySchemeObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#94d60a" port="header"><font face="arial"><b>Security Schemes Map</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="securityScheme1">securityScheme1</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="securityScheme2">securityScheme2</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="securityScheme3">securityScheme3</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">…</td></tr></table>>;];
+  
+  securitySchemeObject [URL = "https://spec.openapis.org/oas/v3.1.0#securitySchemeObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#94d60a" port="header"><font face="arial"><b>Security Scheme Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6ca437">type</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">description</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">name</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">in</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="flows">flows</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">…</td></tr></table>>;];
+  
+  oauthFlowsObject [URL = "https://spec.openapis.org/oas/v3.1.0#oauthFlowsObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#94d60a" port="header"><font face="arial"><b>OAuth Flows Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="implicit">implicit</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="password">password</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="clientCredentials">clientCredentials</td></tr>
+    <tr><td border="1" bgcolor="#6ca437" port="authorizationCode">authorizationCode</td></tr></table>>;];
+  
+  oauthFlowObject [URL = "https://spec.openapis.org/oas/v3.1.0#oauthFlowObject";target = "_blank";label = <<table border="0" cellspacing="0">
+    <tr><td border="1" bgcolor="#94d60a" port="header"><font face="arial"><b>OAuth Flow Object</b></font></td></tr>
+    <tr><td border="1" bgcolor="#6ca437">authorizationUrl</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">tokenUrl</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">refreshUrl</td></tr>
+    <tr><td border="1" bgcolor="#6ca437">scopes</td></tr></table>>;];
+  
+  
+  openapiObject:components -> componentsObject:header;
+  openapiObject:security -> securityRequirementObject:name;
+  
+  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:security -> securityRequirementObject:name;
+  securityRequirementObject:name -> securitySchemesMap:header;
+  
+  componentsObject:securitySchemes -> securitySchemesMap:header;
+  
+  securitySchemesMap:securityScheme1 -> securitySchemeObject:header;
+  securitySchemesMap:securityScheme2 -> securitySchemeObject:header;
+  securitySchemesMap:securityScheme3 -> securitySchemeObject:header;
+  
+  securitySchemeObject:flows -> oauthFlowsObject:header;
+  
+  oauthFlowsObject:implicit -> oauthFlowObject:header;
+  oauthFlowsObject:password -> oauthFlowObject:header;
+  oauthFlowsObject:clientCredentials -> oauthFlowObject:header;
+  oauthFlowsObject:authorizationCode -> oauthFlowObject:header;
+}