Feat: Describing alternative or actual placement of the input security (

#1425) Resolving the long lasting todo. According to https://swagger.io/docs/specification/authentication/api-keys/ Using the specification extensions: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specification-extensions
RobinTail · Dec 26, 2023 · 173ea0f · 173ea0f
1 parent 01ff071
commit 173ea0f
Show file tree

Hide file tree

Showing 6 changed files with 67 additions and 8 deletions.
diff --git a/example/example.documentation.yaml b/example/example.documentation.yaml
@@ -476,6 +476,8 @@ components:
       type: apiKey
       in: query
       name: key
+      x-in-actual: body
+      description: key MUST be supplied within the request body instead of query
     APIKEY_2:
       type: apiKey
       in: header

diff --git a/src/documentation-helpers.ts b/src/documentation-helpers.ts
@@ -914,6 +914,7 @@ export const depictResponse = ({
 
 type SecurityHelper<K extends Security["type"]> = (
   security: Security & { type: K },
+  inputSources?: InputSource[],
 ) => SecuritySchemeObject;
 
 const depictBasicSecurity: SecurityHelper<"basic"> = () => ({
@@ -932,12 +933,26 @@ const depictBearerSecurity: SecurityHelper<"bearer"> = ({
   }
   return result;
 };
-// @todo add description on actual input placement
-const depictInputSecurity: SecurityHelper<"input"> = ({ name }) => ({
-  type: "apiKey",
-  in: "query", // body is not supported yet, https://swagger.io/docs/specification/authentication/api-keys/
-  name,
-});
+const depictInputSecurity: SecurityHelper<"input"> = (
+  { name },
+  inputSources,
+) => {
+  const result: SecuritySchemeObject = {
+    type: "apiKey",
+    in: "query",
+    name,
+  };
+  if (inputSources?.includes("body")) {
+    if (inputSources?.includes("query")) {
+      result["x-in-alternative"] = "body";
+      result.description = `${name} CAN also be supplied within the request body`;
+    } else {
+      result["x-in-actual"] = "body";
+      result.description = `${name} MUST be supplied within the request body instead of query`;
+    }
+  }
+  return result;
+};
 const depictHeaderSecurity: SecurityHelper<"header"> = ({ name }) => ({
   type: "apiKey",
   in: "header",
@@ -970,6 +985,7 @@ const depictOAuth2Security: SecurityHelper<"oauth2"> = ({ flows = {} }) => ({
 
 export const depictSecurity = (
   container: LogicalContainer<Security>,
+  inputSources?: InputSource[],
 ): LogicalContainer<SecuritySchemeObject> => {
   const methods: { [K in Security["type"]]: SecurityHelper<K> } = {
     basic: depictBasicSecurity,
@@ -981,7 +997,10 @@ export const depictSecurity = (
     oauth2: depictOAuth2Security,
   };
   return mapLogicalContainer(container, (security) =>
-    (methods[security.type] as SecurityHelper<typeof security.type>)(security),
+    (methods[security.type] as SecurityHelper<typeof security.type>)(
+      security,
+      inputSources,
+    ),
   );
 };
 

diff --git a/src/documentation.ts b/src/documentation.ts
@@ -223,7 +223,7 @@ export class Documentation extends OpenApiBuilder {
       }
       const securityRefs = depictSecurityRefs(
         mapLogicalContainer(
-          depictSecurity(endpoint.getSecurity()),
+          depictSecurity(endpoint.getSecurity(), inputSources),
           (securitySchema) => {
             const name = this.ensureUniqSecuritySchemaName(securitySchema);
             const scopes = ["oauth2", "openIdConnect"].includes(

diff --git a/tests/unit/__snapshots__/documentation-helpers.spec.ts.snap b/tests/unit/__snapshots__/documentation-helpers.spec.ts.snap
@@ -874,6 +874,26 @@ exports[`Documentation helpers > depictSecurity() > should handle undefined flow
 }
 `;
 
+exports[`Documentation helpers > depictSecurity() > should inform on 'actual' placement of the input security parameter 1`] = `
+{
+  "description": "key MUST be supplied within the request body instead of query",
+  "in": "query",
+  "name": "key",
+  "type": "apiKey",
+  "x-in-actual": "body",
+}
+`;
+
+exports[`Documentation helpers > depictSecurity() > should inform on 'alternative' placement of the input security parameter 1`] = `
+{
+  "description": "key CAN also be supplied within the request body",
+  "in": "query",
+  "name": "key",
+  "type": "apiKey",
+  "x-in-alternative": "body",
+}
+`;
+
 exports[`Documentation helpers > depictSecurityRefs() > should handle LogicalAnd 1`] = `
 [
   {

diff --git a/tests/unit/__snapshots__/documentation.spec.ts.snap b/tests/unit/__snapshots__/documentation.spec.ts.snap
@@ -1685,6 +1685,8 @@ components:
       type: apiKey
       in: query
       name: key
+      x-in-actual: body
+      description: key MUST be supplied within the request body instead of query
     APIKEY_2:
       type: apiKey
       in: header
@@ -2222,6 +2224,8 @@ components:
       type: apiKey
       in: query
       name: key
+      x-in-actual: body
+      description: key MUST be supplied within the request body instead of query
     APIKEY_2:
       type: apiKey
       in: header

diff --git a/tests/unit/documentation-helpers.spec.ts b/tests/unit/documentation-helpers.spec.ts
@@ -1027,6 +1027,20 @@ describe("Documentation helpers", () => {
         }),
       ).toMatchSnapshot();
     });
+    test.each([
+      { variant: "alternative", inputSources: ["query", "body"] as const },
+      { variant: "actual", inputSources: ["body", "files"] as const },
+    ])(
+      `should inform on $variant placement of the input security parameter`,
+      ({ inputSources }) => {
+        expect(
+          depictSecurity(
+            { type: "input", name: "key" },
+            Array.from(inputSources),
+          ),
+        ).toMatchSnapshot();
+      },
+    );
     test("should handle OpenID and OAuth2 Securities", () => {
       expect(
         depictSecurity({