rtk-query-codegen-openapi: If tag is specified and tags exist in a schema, they are now mapped to providesTags or invalidatesTags. (#2071)

* If tags are specified, they are now mapped to providesTags or invalidatesTags.

* npm run format

* npm run test --updateSnapshot

* addTagTypes

* Exported addTagTypes so that the list of addTagTypes can be referenced from outside.

* The tagging function has been made optional.

* add tag test

* code style & method naming

* docs

* addTagTypes does not support injectEndpoints, so it has been moved to enhanceEndpoints.

* Fixed a mistake where providesTags and invalidatesTags were written in the wrong place.

Co-authored-by: Lenz Weber <lenz.weber@mayflower.de>

Author: 2 people

docs/rtk-query/usage/code-generation.mdx

@@ -62,6 +62,15 @@ and then call the code generator:
 npx @rtk-query/codegen-openapi openapi-config.ts
 ```
 
+#### Generating tags
+
+If your OpenAPI specification uses [tags](https://swagger.io/docs/specification/grouping-operations-with-tags/), you can specify the `tag` option to the codegen.  
+That will result in all generated endpoints having `providesTags`/`invalidatesTags` declarations for the `tags` of their respective operation definition.
+
+Note that this will only result in string tags with no ids, so it might lead to scenarios where too much is invalidated and unneccessary requests are made on mutation.
+
+In that case it is still recommended to manually specify tags by using [`enhanceEndpoints`](./code-splitting.mdx) on top of the generated api and manually declare `providesTags`/`invalidatesTags`.
+
 ### Programmatic usage
 
 ```ts no-transpile title="src/store/petApi.ts"
@@ -90,6 +99,7 @@ interface SimpleUsage {
   hooks?:
     | boolean
     | { queries: boolean; lazyQueries: boolean; mutations: boolean }
+  tag?: boolean
   outputFile: string
   filterEndpoints?:
     | string

packages/rtk-query-codegen-openapi/src/codegen.ts

@@ -3,9 +3,11 @@ import { factory } from './utils/factory';
 
 const defaultEndpointBuilder = factory.createIdentifier('build');
 
-export type ObjectPropertyDefinitions = Record<string, ts.Expression>;
+export type ObjectPropertyDefinitions = Record<string, ts.Expression | undefined>;
 export function generateObjectProperties(obj: ObjectPropertyDefinitions) {
-  return Object.entries(obj).map(([k, v]) => factory.createPropertyAssignment(factory.createIdentifier(k), v));
+  return Object.entries(obj)
+    .filter(([_, v]) => v)
+    .map(([k, v]) => factory.createPropertyAssignment(factory.createIdentifier(k), v as ts.Expression));
 }
 
 export function generateImportNode(pkg: string, namedImports: Record<string, string>, defaultImportName?: string) {
@@ -31,10 +33,69 @@ export function generateImportNode(pkg: string, namedImports: Record<string, str
 export function generateCreateApiCall({
   endpointBuilder = defaultEndpointBuilder,
   endpointDefinitions,
+  tag,
 }: {
   endpointBuilder?: ts.Identifier;
   endpointDefinitions: ts.ObjectLiteralExpression;
+  tag: boolean;
 }) {
+  const injectEndpointsObjectLiteralExpression = factory.createObjectLiteralExpression(
+    generateObjectProperties({
+      endpoints: factory.createArrowFunction(
+        undefined,
+        undefined,
+        [
+          factory.createParameterDeclaration(
+            undefined,
+            undefined,
+            undefined,
+            endpointBuilder,
+            undefined,
+            undefined,
+            undefined
+          ),
+        ],
+        undefined,
+        factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+        factory.createParenthesizedExpression(endpointDefinitions)
+      ),
+      overrideExisting: factory.createFalse(),
+    }),
+    true
+  );
+  if (tag) {
+    const enhanceEndpointsObjectLiteralExpression = factory.createObjectLiteralExpression(
+      [factory.createShorthandPropertyAssignment(factory.createIdentifier('addTagTypes'), undefined)],
+      true
+    )
+    return factory.createVariableStatement(
+      undefined,
+      factory.createVariableDeclarationList(
+        [factory.createVariableDeclaration(
+          factory.createIdentifier("injectedRtkApi"),
+          undefined,
+          undefined,
+          factory.createCallExpression(
+            factory.createPropertyAccessExpression(
+              factory.createCallExpression(
+                factory.createPropertyAccessExpression(
+                  factory.createIdentifier("api"),
+                  factory.createIdentifier("enhanceEndpoints")
+                ),
+                undefined,
+                [enhanceEndpointsObjectLiteralExpression]
+              ),
+              factory.createIdentifier("injectEndpoints")
+            ),
+            undefined,
+            [injectEndpointsObjectLiteralExpression]
+          )
+        )],
+        ts.NodeFlags.Const
+      )
+    );
+  }
+
   return factory.createVariableStatement(
     undefined,
     factory.createVariableDeclarationList(
@@ -49,32 +110,7 @@ export function generateCreateApiCall({
               factory.createIdentifier('injectEndpoints')
             ),
             undefined,
-            [
-              factory.createObjectLiteralExpression(
-                generateObjectProperties({
-                  endpoints: factory.createArrowFunction(
-                    undefined,
-                    undefined,
-                    [
-                      factory.createParameterDeclaration(
-                        undefined,
-                        undefined,
-                        undefined,
-                        endpointBuilder,
-                        undefined,
-                        undefined,
-                        undefined
-                      ),
-                    ],
-                    undefined,
-                    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
-                    factory.createParenthesizedExpression(endpointDefinitions)
-                  ),
-                  overrideExisting: factory.createFalse(),
-                }),
-                true
-              ),
-            ]
+            [injectEndpointsObjectLiteralExpression]
           )
         ),
       ],
@@ -91,6 +127,7 @@ export function generateEndpointDefinition({
   queryFn,
   endpointBuilder = defaultEndpointBuilder,
   extraEndpointsProps,
+  tags,
 }: {
   operationName: string;
   type: 'query' | 'mutation';
@@ -99,7 +136,17 @@ export function generateEndpointDefinition({
   queryFn: ts.Expression;
   endpointBuilder?: ts.Identifier;
   extraEndpointsProps: ObjectPropertyDefinitions;
+  tags: string[];
 }) {
+  const objectProperties = generateObjectProperties({ query: queryFn, ...extraEndpointsProps });
+  if (tags.length > 0) {
+    objectProperties.push(
+      factory.createPropertyAssignment(
+        factory.createIdentifier(type === 'query' ? 'providesTags' : 'invalidatesTags'),
+        factory.createArrayLiteralExpression(tags.map((tag) => factory.createStringLiteral(tag), false))
+      )
+    )
+  }
   return factory.createPropertyAssignment(
     factory.createIdentifier(operationName),
 
@@ -108,10 +155,33 @@ export function generateEndpointDefinition({
       [Response, QueryArg],
       [
         factory.createObjectLiteralExpression(
-          generateObjectProperties({ query: queryFn, ...extraEndpointsProps }),
+          objectProperties,
           true
         ),
       ]
+    ),
+  );
+}
+
+export function generateTagTypes({ addTagTypes }: { addTagTypes: string[] }) {
+  return factory.createVariableStatement(
+    [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
+    factory.createVariableDeclarationList(
+      [
+        factory.createVariableDeclaration(
+          factory.createIdentifier('addTagTypes'),
+          undefined,
+          undefined,
+          factory.createAsExpression(
+            factory.createArrayLiteralExpression(
+              addTagTypes.map((tagType) => factory.createStringLiteral(tagType)),
+              true
+            ),
+            factory.createTypeReferenceNode(factory.createIdentifier('const'), undefined)
+          )
+        ),
+      ],
+      ts.NodeFlags.Const
     )
   );
 }

packages/rtk-query-codegen-openapi/src/generate.ts

@@ -17,6 +17,7 @@ import type { OpenAPIV3 } from 'openapi-types';
 import { generateReactHooks } from './generators/react-hooks';
 import type { EndpointMatcher, EndpointOverrides, GenerationOptions, OperationDefinition, TextMatcher } from './types';
 import { capitalize, getOperationDefinitions, getV3Doc, isQuery as testIsQuery, removeUndefined } from './utils';
+import { generateTagTypes } from './codegen';
 import type { ObjectPropertyDefinitions } from './codegen';
 import { generateCreateApiCall, generateEndpointDefinition, generateImportNode } from './codegen';
 import { factory } from './utils/factory';
@@ -32,6 +33,10 @@ function getOperationName({ verb, path, operation }: Pick<OperationDefinition, '
   return _getOperationName(verb, path, operation.operationId);
 }
 
+function getTags({ verb, pathItem }: Pick<OperationDefinition, 'verb' | 'pathItem'>): string[] {
+  return verb ? pathItem[verb]?.tags || [] : [];
+}
+
 function patternMatches(pattern?: TextMatcher) {
   const filters = Array.isArray(pattern) ? pattern : [pattern];
   return function matcher(operationName: string) {
@@ -67,6 +72,7 @@ export async function generateApi(
     argSuffix = 'ApiArg',
     responseSuffix = 'ApiResponse',
     hooks = false,
+    tag = false,
     outputFile,
     isDataResponse = defaultIsDataResponse,
     filterEndpoints,
@@ -116,7 +122,9 @@ export async function generateApi(
     factory.createSourceFile(
       [
         generateImportNode(apiFile, { [apiImport]: 'api' }),
+        ...(tag ? [generateTagTypes({ addTagTypes: extractAllTagTypes({ operationDefinitions }) })] : []),
         generateCreateApiCall({
+          tag,
           endpointDefinitions: factory.createObjectLiteralExpression(
             operationDefinitions.map((operationDefinition) =>
               generateEndpoint({
@@ -160,6 +168,18 @@ export async function generateApi(
 
   return sourceCode;
 
+  function extractAllTagTypes({ operationDefinitions }: { operationDefinitions: OperationDefinition[] }) {
+    let allTagTypes = new Set<string>();
+
+    for (const operationDefinition of operationDefinitions) {
+      const { verb, pathItem } = operationDefinition;
+      for (const tag of getTags({ verb, pathItem })) {
+        allTagTypes.add(tag);
+      }
+    }
+    return [...allTagTypes];
+  }
+
   function generateEndpoint({
     operationDefinition,
     overrides,
@@ -175,7 +195,7 @@ export async function generateApi(
       operation: { responses, requestBody },
     } = operationDefinition;
     const operationName = getOperationName({ verb, path, operation });
-
+    const tags = tag ? getTags({ verb, pathItem }) : [];
     const isQuery = testIsQuery(verb, overrides);
 
     const returnsJson = apiGen.getResponseType(responses) === 'json';
@@ -309,21 +329,24 @@ export async function generateApi(
       type: isQuery ? 'query' : 'mutation',
       Response: ResponseTypeName,
       QueryArg,
-      queryFn: generateQueryFn({ operationDefinition, queryArg, isQuery }),
+      queryFn: generateQueryFn({ operationDefinition, queryArg, isQuery, tags }),
       extraEndpointsProps: isQuery
         ? generateQueryEndpointProps({ operationDefinition })
         : generateMutationEndpointProps({ operationDefinition }),
+      tags,
     });
   }
 
   function generateQueryFn({
     operationDefinition,
     queryArg,
     isQuery,
+    tags,
   }: {
     operationDefinition: OperationDefinition;
     queryArg: QueryArgDefinitions;
     isQuery: boolean;
+    tags: string[];
   }) {
     const { path, verb } = operationDefinition;
 

packages/rtk-query-codegen-openapi/src/types.ts

@@ -51,11 +51,14 @@ export interface CommonOptions {
    * `true` will generate hooks for queries and mutations, but no lazyQueries
    */
   hooks?: boolean | { queries: boolean; lazyQueries: boolean; mutations: boolean };
-
   /**
    * defaults to false
    */
   unionUndefined?: boolean;
+  /**
+   * defaults to false
+   */
+  tag?: boolean;
 }
 
 export type TextMatcher = string | RegExp | (string | RegExp)[];

packages/rtk-query-codegen-openapi/src/utils/getOperationDefinitions.ts

@@ -1,5 +1,5 @@
 import type { OpenAPIV3 } from 'openapi-types';
-import type { OperationDefinition} from '../types';
+import type { OperationDefinition } from '../types';
 import { operationKeys } from '../types';
 
 export function getOperationDefinitions(v3Doc: OpenAPIV3.Document): OperationDefinition[] {