From 8162786d7cf4c75869fe53d9e8bfd98003cfbf20 Mon Sep 17 00:00:00 2001 From: Lucas zapico <12178702+LucasZapico@users.noreply.github.com> Date: Thu, 10 Oct 2024 07:35:20 -0700 Subject: [PATCH] docs: enhance REST API OpenAPI spec with nested filter example (#7366) --- .../utils/__tests__/parameters.utils.spec.ts | 16 +++++++++++----- .../open-api/utils/parameters.utils.ts | 14 +++++++++++--- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/packages/twenty-server/src/engine/core-modules/open-api/utils/__tests__/parameters.utils.spec.ts b/packages/twenty-server/src/engine/core-modules/open-api/utils/__tests__/parameters.utils.spec.ts index 0a15ff0fd1b3..bab186af5231 100644 --- a/packages/twenty-server/src/engine/core-modules/open-api/utils/__tests__/parameters.utils.spec.ts +++ b/packages/twenty-server/src/engine/core-modules/open-api/utils/__tests__/parameters.utils.spec.ts @@ -1,5 +1,9 @@ import { OrderByDirection } from 'src/engine/api/graphql/workspace-query-builder/interfaces/record.interface'; +import { DEFAULT_CONJUNCTION } from 'src/engine/api/rest/core/query-builder/utils/filter-utils/add-default-conjunction.utils'; +import { FilterComparators } from 'src/engine/api/rest/core/query-builder/utils/filter-utils/parse-base-filter.utils'; +import { Conjunctions } from 'src/engine/api/rest/core/query-builder/utils/filter-utils/parse-filter.utils'; +import { DEFAULT_ORDER_DIRECTION } from 'src/engine/api/rest/input-factories/order-by-input.factory'; import { computeDepthParameters, computeEndingBeforeParameters, @@ -9,10 +13,6 @@ import { computeOrderByParameters, computeStartingAfterParameters, } from 'src/engine/core-modules/open-api/utils/parameters.utils'; -import { DEFAULT_ORDER_DIRECTION } from 'src/engine/api/rest/input-factories/order-by-input.factory'; -import { FilterComparators } from 'src/engine/api/rest/core/query-builder/utils/filter-utils/parse-base-filter.utils'; -import { Conjunctions } from 'src/engine/api/rest/core/query-builder/utils/filter-utils/parse-filter.utils'; -import { DEFAULT_CONJUNCTION } from 'src/engine/api/rest/core/query-builder/utils/filter-utils/add-default-conjunction.utils'; describe('computeParameters', () => { describe('computeLimit', () => { @@ -83,7 +83,9 @@ describe('computeParameters', () => { name: 'filter', in: 'query', description: `Filters objects returned. - Should have the following shape: **field_1[COMPARATOR]:value_1,field_2[COMPARATOR]:value_2,...** + Should have the following shape: **field_1[COMPARATOR]:value_1,field_2[COMPARATOR]:value_2... + To filter on nested objects use **field.nestedField[COMPARATOR]:value_1 + ** Available comparators are **${Object.values(FilterComparators).join( '**, **', )}**. @@ -102,6 +104,10 @@ describe('computeParameters', () => { value: 'createdAt[gte]:"2023-01-01"', description: 'A simple filter param', }, + simpleNested: { + value: 'emails.primaryEmail[eq]:foo99@example.com', + description: 'A simple nested filter param', + }, complex: { value: 'or(createdAt[gte]:"2024-01-01",createdAt[lte]:"2023-01-01",not(id[is]:NULL))', diff --git a/packages/twenty-server/src/engine/core-modules/open-api/utils/parameters.utils.ts b/packages/twenty-server/src/engine/core-modules/open-api/utils/parameters.utils.ts index ca009395f3b4..9cb95402c191 100644 --- a/packages/twenty-server/src/engine/core-modules/open-api/utils/parameters.utils.ts +++ b/packages/twenty-server/src/engine/core-modules/open-api/utils/parameters.utils.ts @@ -2,10 +2,10 @@ import { OpenAPIV3_1 } from 'openapi-types'; import { OrderByDirection } from 'src/engine/api/graphql/workspace-query-builder/interfaces/record.interface'; +import { DEFAULT_CONJUNCTION } from 'src/engine/api/rest/core/query-builder/utils/filter-utils/add-default-conjunction.utils'; import { FilterComparators } from 'src/engine/api/rest/core/query-builder/utils/filter-utils/parse-base-filter.utils'; import { Conjunctions } from 'src/engine/api/rest/core/query-builder/utils/filter-utils/parse-filter.utils'; import { DEFAULT_ORDER_DIRECTION } from 'src/engine/api/rest/input-factories/order-by-input.factory'; -import { DEFAULT_CONJUNCTION } from 'src/engine/api/rest/core/query-builder/utils/filter-utils/add-default-conjunction.utils'; export const computeLimitParameters = ( fromMetadata = false, @@ -73,7 +73,9 @@ export const computeFilterParameters = (): OpenAPIV3_1.ParameterObject => { name: 'filter', in: 'query', description: `Filters objects returned. - Should have the following shape: **field_1[COMPARATOR]:value_1,field_2[COMPARATOR]:value_2,...** + Should have the following shape: **field_1[COMPARATOR]:value_1,field_2[COMPARATOR]:value_2... + To filter on nested objects use **field.nestedField[COMPARATOR]:value_1 + ** Available comparators are **${Object.values(FilterComparators).join( '**, **', )}**. @@ -82,7 +84,9 @@ export const computeFilterParameters = (): OpenAPIV3_1.ParameterObject => { ).join('**, **')}**. Default root conjunction is **${DEFAULT_CONJUNCTION}**. To filter **null** values use **field[is]:NULL** or **field[is]:NOT_NULL** - To filter using **boolean** values use **field[eq]:true** or **field[eq]:false**`, + To filter using **boolean** values use **field[eq]:true** or **field[eq]:false** + `, + required: false, schema: { type: 'string', @@ -92,6 +96,10 @@ export const computeFilterParameters = (): OpenAPIV3_1.ParameterObject => { value: 'createdAt[gte]:"2023-01-01"', description: 'A simple filter param', }, + simpleNested: { + value: 'emails.primaryEmail[eq]:foo99@example.com', + description: 'A simple nested filter param', + }, complex: { value: 'or(createdAt[gte]:"2024-01-01",createdAt[lte]:"2023-01-01",not(id[is]:NULL))',