Merge pull request #419 from OpenAPI-Qraft/feat/top-level-security-support

feat: root level security support

Author: radist2s

.changeset/swift-sheep-report.md

@@ -0,0 +1,5 @@
+---
+'@openapi-qraft/tanstack-query-react-plugin': minor
+---
+
+Added an optional `--root-security` flag that applies the OpenAPI document’s top-level `security` as the default for operations that omit their own `security`, while any operation-level `security` still overrides it as defined by the specification.

packages/cli/src/bin.test.ts

@@ -117,6 +117,7 @@ describe('CLI binary help output', () => {
           --explicit-import-extensions [extension]                      All import statements will contain an explicit file extension. Ideal for projects using ECMAScript modules. (choices: ".js", ".ts", preset: ".js")
           --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. Default: true when --plugin openapi-typescript is used.
           --queryable-write-operations [bool]                           Enable generation of query hooks (useQuery, useSuspenseQuery, etc.) for writable HTTP methods like POST, PUT, PATCH. By default, only mutation hooks are generated for writable operations.
+          --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.
           --create-api-client-fn <functionName> [options...]            Configure API client creation function. Allows specifying the function name, included services, and callbacks. Can be specified multiple times to generate several different API client functions from a single OpenAPI document. (default: null)
           --override-import-type <pathname overrides...>                Override import paths for specific types in generated files. This allows using custom type implementations instead of the default ones. Expected format: filepath originalModule:importTypeName:customImportPath
           --operation-parameters-type-wrapper <parameters wrappers...>  Configure ParametersWrapper types for specific operation patterns. Expected format: pattern type:TypeName import:ImportPath. Can be specified multiple times for different patterns.
@@ -214,6 +215,7 @@ describe('CLI binary help output', () => {
           --explicit-import-extensions [extension]                      All import statements will contain an explicit file extension. Ideal for projects using ECMAScript modules. (choices: ".js", ".ts", preset: ".js")
           --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. Default: true when --plugin openapi-typescript is used. (default: true)
           --queryable-write-operations [bool]                           Enable generation of query hooks (useQuery, useSuspenseQuery, etc.) for writable HTTP methods like POST, PUT, PATCH. By default, only mutation hooks are generated for writable operations.
+          --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.
           --create-api-client-fn <functionName> [options...]            Configure API client creation function. Allows specifying the function name, included services, and callbacks. Can be specified multiple times to generate several different API client functions from a single OpenAPI document. (default: null)
           --override-import-type <pathname overrides...>                Override import paths for specific types in generated files. This allows using custom type implementations instead of the default ones. Expected format: filepath originalModule:importTypeName:customImportPath
           --operation-parameters-type-wrapper <parameters wrappers...>  Configure ParametersWrapper types for specific operation patterns. Expected format: pattern type:TypeName import:ImportPath. Can be specified multiple times for different patterns.

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
 

packages/openapi-plugin/src/lib/open-api/OpenAPISchemaType.ts

@@ -4,6 +4,7 @@ export type OpenAPISchemaType = {
     title: string;
     version: string;
   };
+  security?: Array<Record<string, string[] | undefined>>;
   paths: {
     [path: string]: {
       [method: string]: {
@@ -23,7 +24,7 @@ export type OpenAPISchemaType = {
           required?: boolean;
         };
         responses: {
-          [statusCode in number | 'default']: {
+          [statusCode in number | 'default']?: {
             $ref?: string;
             description?: string;
             content?: {

packages/openapi-plugin/src/lib/open-api/getServices.ts

@@ -66,6 +66,7 @@ export const getServices = (
         >
       >(
         (acc, [statusCode, response]) => {
+          if (!response) return acc;
           if (response.$ref) {
             response = resolveDocumentLocalRef(
               response.$ref,