feat: add --root-security option to support root-level OpenAPI security in generated schemas

Author: radist2s

packages/openapi-cli/README.md

@@ -36,6 +36,7 @@ Options:
                                                       example: "post /**:[A-Za-z]+Id ==> createOne"
   --postfix-services <string>                         Postfix to be added to the generated service name (eg: Service)
   --service-name-base <endpoint[<index>] | tags>      Use OpenAPI Operation `endpoint[<index>]` path part (e.g.: "/0/1/2") or `tags` as the base name of the service. (default: "endpoint[0]")
+  --root-security                                     Use root-level OpenAPI security as the default for operations without their own security. Operation-level security overrides it according to OpenAPI semantics.
   --file-header <string>                              Header to be added to the generated file (eg: /* eslint-disable */)
   --redocly [config]                                  Use the Redocly configuration to generate multiple API clients
                                                       If the [config] parameter is not specified, the default Redocly configuration will be used: [redocly.yaml | redocly.yml | .redocly.yaml |
@@ -210,6 +211,9 @@ The following plugins are currently supported:
       - `--openapi-types-import-path '@/api/openapi.d.ts'`
       - `--openapi-types-import-path '@external-package-types'`
 - **`--export-openapi-types [bool]`:** Add an export statement of the generated OpenAPI document types from the `./index.ts` file. Useful for sharing types within your project. _(optional, default: `true`, if `--plugin openapi-typescript` is used)_
+- **`--root-security`**: Use root-level OpenAPI `security` as the default for operations that do not define their own `security`. Operation-level `security` overrides it according to OpenAPI semantics. _(optional, disabled by default)_
+  - Use this option when your OpenAPI document defines `security` on the top level and you want generated operation schemas to include those security requirements automatically.
+  - Without this option, only operation-level `security` is emitted into generated schemas.
 
 ### `--plugin openapi-typescript` options
 

website/docs/authorization/qraft-secure-request-fn.mdx

@@ -17,6 +17,14 @@ See the [OpenAPI Authentication 🔗](https://swagger.io/docs/specification/auth
 This feature is still in the experimental stage 🧪 and may change in the future.
 :::
 
+:::tip
+`QraftSecureRequestFn` relies on generated operation `schema.security`.
+
+If your OpenAPI document defines `security` on the top level, generate the client with `--root-security`
+so those root-level security requirements are included in generated operation schemas.
+Without `--root-security`, only operation-level `security` is emitted by the generator.
+:::
+
 ```tsx
 import { createAPIClient } from './api'; // generated by OpenAPI Qraft CLI
 import { requestFn } from '@openapi-qraft/react';
@@ -100,11 +108,12 @@ In this example, the `mySecurityScheme` security scheme handler is used to obtai
   <TabItem value="1. Open API Document">
     ```yaml
     openapi: 3.1.0
-    securitySchemes:
-      mySecurityScheme: # ⬅︎ Define security scheme
-        type: http
-        scheme: bearer
-        bearerFormat: JWT
+    components:
+      securitySchemes:
+        mySecurityScheme: # ⬅︎ Define security scheme
+          type: http
+          scheme: bearer
+          bearerFormat: JWT
     paths:
       /pet:
         post:

website/docs/codegen/openapi/index.mdx

@@ -226,6 +226,10 @@ It is possible to use multiple plugins at the same time. For example, `--plugin
   instead of command-line parameters. See the [Redocly configuration documentation](../cli/redocly-config.mdx#generating-multiple-api-client-functions)
   for more details on how to configure multiple _create API client functions_ in a YAML file.
   ::::
+- **`--root-security`**: Use root-level OpenAPI `security` as the default for operations that do not define their own `security`. Operation-level `security` overrides it according to OpenAPI semantics. _(optional, disabled by default)_
+  - Use this option when your OpenAPI document defines `security` on the top level and you want generated operation schemas to include those security requirements automatically.
+  - Without this option, Qraft only includes operation-level `security` in generated schemas.
+  - This is especially useful together with [`QraftSecureRequestFn`](../../authorization/qraft-secure-request-fn.mdx), because secure handlers rely on generated operation `schema.security`.
 
 ## `--plugin openapi-typescript` options