feat(security): more endpoint + flow type examples (#114)

readmeio · Aug 29, 2024 · aa1b559 · aa1b559
1 parent 3fc3793
commit aa1b559
Show file tree

Hide file tree

Showing 4 changed files with 388 additions and 17 deletions.
diff --git a/3.0/json/security.json b/3.0/json/security.json
@@ -126,7 +126,7 @@
     },
     "/anything/oauth2": {
       "post": {
-        "summary": "General support",
+        "summary": "General support (all flow types)",
         "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23",
         "tags": ["OAuth 2"],
         "responses": {
@@ -139,6 +139,66 @@
             "oauth2": ["write:things"]
           }
         ]
+      },
+      "get": {
+        "summary": "General support (authorizationCode flow type)",
+        "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23",
+        "tags": ["OAuth 2"],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        },
+        "security": [
+          {
+            "oauth2_authorizationCode": ["write:things"]
+          }
+        ]
+      },
+      "put": {
+        "summary": "General support (clientCredentials flow type)",
+        "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23",
+        "tags": ["OAuth 2"],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        },
+        "security": [
+          {
+            "oauth2_clientCredentials": ["write:things"]
+          }
+        ]
+      },
+      "patch": {
+        "summary": "General support (implicit flow type)",
+        "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23",
+        "tags": ["OAuth 2"],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        },
+        "security": [
+          {
+            "oauth2_implicit": ["write:things"]
+          }
+        ]
+      },
+      "delete": {
+        "summary": "General support (password flow type)",
+        "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23",
+        "tags": ["OAuth 2"],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        },
+        "security": [
+          {
+            "oauth2_password": ["write:things"]
+          }
+        ]
       }
     },
     "/anything/openIdConnect": {
@@ -273,9 +333,34 @@
           }
         }
       },
-      "oauth2_alternate": {
+      "oauth2_authorizationCode": {
         "type": "oauth2",
-        "description": "An alternate OAuth 2 security flow. Functions identially to the other `oauth2` scheme, just with alternate URLs to authenticate against. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23",
+        "description": "An OAuth 2 security flow that only supports the `authorizationCode` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object",
+        "flows": {
+          "authorizationCode": {
+            "authorizationUrl": "http://alt.example.com/oauth/dialog",
+            "tokenUrl": "http://alt.example.com/oauth/token",
+            "scopes": {
+              "write:things": "Add things to your account"
+            }
+          }
+        }
+      },
+      "oauth2_clientCredentials": {
+        "type": "oauth2",
+        "description": "An OAuth 2 security flow that only supports the `clientCredentials` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object",
+        "flows": {
+          "clientCredentials": {
+            "tokenUrl": "http://alt.example.com/oauth/token",
+            "scopes": {
+              "write:things": "Add things to your account"
+            }
+          }
+        }
+      },
+      "oauth2_implicit": {
+        "type": "oauth2",
+        "description": "An OAuth 2 security flow that only supports the `implicit` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object",
         "flows": {
           "implicit": {
             "authorizationUrl": "http://alt.example.com/oauth/dialog",
@@ -285,6 +370,18 @@
           }
         }
       },
+      "oauth2_password": {
+        "type": "oauth2",
+        "description": "An OAuth 2 security flow that only supports the `password` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object",
+        "flows": {
+          "password": {
+            "tokenUrl": "http://alt.example.com/oauth/token",
+            "scopes": {
+              "write:things": "Add things to your account"
+            }
+          }
+        }
+      },
       "openIdConnect": {
         "type": "openIdConnect",
         "openIdConnectUrl": "https://example.com/.well-known/openid-configuration",

diff --git a/3.0/yaml/security.yaml b/3.0/yaml/security.yaml
@@ -89,7 +89,7 @@ paths:
         - bearer_jwt: []
   '/anything/oauth2':
     post:
-      summary: General support
+      summary: General support (all flow types)
       description: |-
         > ℹ️
         > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.
@@ -103,6 +103,66 @@ paths:
       security:
         - oauth2:
             - write:things
+    get:
+      summary: General support (authorizationCode flow type)
+      description: |-
+        > ℹ️
+        > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.
+
+        https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23
+      tags:
+        - OAuth 2
+      responses:
+        '200':
+          description: OK
+      security:
+        - oauth2_authorizationCode:
+            - write:things
+    put:
+      summary: General support (clientCredentials flow type)
+      description: |-
+        > ℹ️
+        > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.
+
+        https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23
+      tags:
+        - OAuth 2
+      responses:
+        '200':
+          description: OK
+      security:
+        - oauth2_clientCredentials:
+            - write:things
+    patch:
+      summary: General support (implicit flow type)
+      description: |-
+        > ℹ️
+        > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.
+
+        https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23
+      tags:
+        - OAuth 2
+      responses:
+        '200':
+          description: OK
+      security:
+        - oauth2_implicit:
+            - write:things
+    delete:
+      summary: General support (password flow type)
+      description: |-
+        > ℹ️
+        > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.
+
+        https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23
+      tags:
+        - OAuth 2
+      responses:
+        '200':
+          description: OK
+      security:
+        - oauth2_password:
+            - write:things
   '/anything/openIdConnect':
     post:
       summary: General support
@@ -205,15 +265,43 @@ components:
           tokenUrl: http://example.com/oauth/token
           scopes:
             write:things: Add things to your account
-    oauth2_alternate:
+    oauth2_authorizationCode:
       type: oauth2
-      description: An alternate OAuth 2 security flow. Functions identially to the
-        other `oauth2` scheme, just with alternate URLs to authenticate against. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23
+      description: An OAuth 2 security flow that only supports the `authorizationCode`
+        flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object
+      flows:
+        authorizationCode:
+          authorizationUrl: http://alt.example.com/oauth/dialog
+          tokenUrl: http://alt.example.com/oauth/token
+          scopes:
+            write:things: Add things to your account
+    oauth2_clientCredentials:
+      type: oauth2
+      description: An OAuth 2 security flow that only supports the `clientCredentials`
+        flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object
+      flows:
+        clientCredentials:
+          tokenUrl: http://alt.example.com/oauth/token
+          scopes:
+            write:things: Add things to your account
+    oauth2_implicit:
+      type: oauth2
+      description: An OAuth 2 security flow that only supports the `implicit` flow
+        type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object
       flows:
         implicit:
           authorizationUrl: http://alt.example.com/oauth/dialog
           scopes:
             write:things: Add things to your account
+    oauth2_password:
+      type: oauth2
+      description: An OAuth 2 security flow that only supports the `password` flow
+        type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object
+      flows:
+        password:
+          tokenUrl: http://alt.example.com/oauth/token
+          scopes:
+            write:things: Add things to your account
     openIdConnect:
       type: openIdConnect
       openIdConnectUrl: https://example.com/.well-known/openid-configuration

diff --git a/3.1/json/security.json b/3.1/json/security.json
@@ -145,8 +145,8 @@
     },
     "/anything/oauth2": {
       "post": {
-        "summary": "General support",
-        "description": ">ℹ️We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23",
+        "summary": "General support (all flow types)",
+        "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23",
         "tags": ["OAuth 2"],
         "responses": {
           "200": {
@@ -158,6 +158,66 @@
             "oauth2": ["write:things"]
           }
         ]
+      },
+      "get": {
+        "summary": "General support (authorizationCode flow type)",
+        "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23",
+        "tags": ["OAuth 2"],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        },
+        "security": [
+          {
+            "oauth2_authorizationCode": ["write:things"]
+          }
+        ]
+      },
+      "put": {
+        "summary": "General support (clientCredentials flow type)",
+        "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23",
+        "tags": ["OAuth 2"],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        },
+        "security": [
+          {
+            "oauth2_clientCredentials": ["write:things"]
+          }
+        ]
+      },
+      "patch": {
+        "summary": "General support (implicit flow type)",
+        "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23",
+        "tags": ["OAuth 2"],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        },
+        "security": [
+          {
+            "oauth2_implicit": ["write:things"]
+          }
+        ]
+      },
+      "delete": {
+        "summary": "General support (password flow type)",
+        "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23",
+        "tags": ["OAuth 2"],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        },
+        "security": [
+          {
+            "oauth2_password": ["write:things"]
+          }
+        ]
       }
     },
     "/anything/openIdConnect": {
@@ -278,9 +338,34 @@
           }
         }
       },
-      "oauth2_alternate": {
+      "oauth2_authorizationCode": {
+        "type": "oauth2",
+        "description": "An OAuth 2 security flow that only supports the `authorizationCode` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object",
+        "flows": {
+          "authorizationCode": {
+            "authorizationUrl": "http://alt.example.com/oauth/dialog",
+            "tokenUrl": "http://alt.example.com/oauth/token",
+            "scopes": {
+              "write:things": "Add things to your account"
+            }
+          }
+        }
+      },
+      "oauth2_clientCredentials": {
         "type": "oauth2",
-        "description": "An alternate OAuth 2 security flow. Functions identially to the other `oauth2` scheme, just with alternate URLs to authenticate against. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23",
+        "description": "An OAuth 2 security flow that only supports the `clientCredentials` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object",
+        "flows": {
+          "clientCredentials": {
+            "tokenUrl": "http://alt.example.com/oauth/token",
+            "scopes": {
+              "write:things": "Add things to your account"
+            }
+          }
+        }
+      },
+      "oauth2_implicit": {
+        "type": "oauth2",
+        "description": "An OAuth 2 security flow that only supports the `implicit` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object",
         "flows": {
           "implicit": {
             "authorizationUrl": "http://alt.example.com/oauth/dialog",
@@ -290,6 +375,18 @@
           }
         }
       },
+      "oauth2_password": {
+        "type": "oauth2",
+        "description": "An OAuth 2 security flow that only supports the `password` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object",
+        "flows": {
+          "password": {
+            "tokenUrl": "http://alt.example.com/oauth/token",
+            "scopes": {
+              "write:things": "Add things to your account"
+            }
+          }
+        }
+      },
       "openIdConnect": {
         "type": "openIdConnect",
         "openIdConnectUrl": "https://example.com/.well-known/openid-configuration",