From 0a194c675266449c388b0e70a0ee56fc1e545fa7 Mon Sep 17 00:00:00 2001 From: Mostafa Moradian Date: Sat, 22 Jun 2024 19:19:00 +0200 Subject: [PATCH 1/3] fix: change special character to fix root paramter naming issue feat: add customParameters function for fixing tenantId error on `/api/.well-known/endpoints/{tenantId}` --- packages/core/src/routes/swagger/index.ts | 7 +++++- .../src/routes/swagger/utils/parameters.ts | 22 +++++++++++++++++-- 2 files changed, 26 insertions(+), 3 deletions(-) diff --git a/packages/core/src/routes/swagger/index.ts b/packages/core/src/routes/swagger/index.ts index 19d8f743e40..a15c38e4ef7 100644 --- a/packages/core/src/routes/swagger/index.ts +++ b/packages/core/src/routes/swagger/index.ts @@ -34,6 +34,7 @@ import { paginationParameters, buildPathIdParameters, mergeParameters, + customParameters, } from './utils/parameters.js'; type RouteObject = { @@ -232,7 +233,11 @@ export default function swaggerRoutes ({ ...previous, ...buildPathIdParameters(entityName) }), + (previous, entityName) => ({ + ...previous, + ...buildPathIdParameters(entityName), + ...customParameters(), + }), {} ), }, diff --git a/packages/core/src/routes/swagger/utils/parameters.ts b/packages/core/src/routes/swagger/utils/parameters.ts index 49bbd20a6df..f623780696a 100644 --- a/packages/core/src/routes/swagger/utils/parameters.ts +++ b/packages/core/src/routes/swagger/utils/parameters.ts @@ -91,7 +91,7 @@ export const buildParameters: BuildParameters = ( if (key === 'id') { if (rootComponent) { return { - $ref: `#/components/parameters/${pluralize(rootComponent, 1)}Id:root`, + $ref: `#/components/parameters/${pluralize(rootComponent, 1)}Id-root`, }; } @@ -241,7 +241,7 @@ export const buildPathIdParameters = ( // Need to duplicate the object because OpenAPI does not support partial reference. // See https://github.com/OAI/OpenAPI-Specification/issues/2026 return { - [`${entityId}:root`]: { + [`${entityId}-root`]: { ...shared, name: 'id', }, @@ -251,3 +251,21 @@ export const buildPathIdParameters = ( }, }; }; + +/** + * Build a parameter object for the `tenantId` parameter. + * @returns The parameter object for the `tenantId` parameter. + */ +export const customParameters = (): Record => { + return { + tenantId: { + name: 'tenantId', + in: 'path', + description: 'The unique identifier of the tenant.', + required: true, + schema: { + type: 'string', + }, + }, + }; +}; From e24ff76c1fc138b760fe8bec94fc6286946d1ac1 Mon Sep 17 00:00:00 2001 From: Mostafa Moradian Date: Sat, 22 Jun 2024 23:33:13 +0200 Subject: [PATCH 2/3] fix: update mocks and docstrings --- packages/core/src/routes/swagger/index.test.ts | 4 ++-- packages/core/src/routes/swagger/utils/parameters.ts | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/core/src/routes/swagger/index.test.ts b/packages/core/src/routes/swagger/index.test.ts index 769a64fe572..7444f2d6761 100644 --- a/packages/core/src/routes/swagger/index.test.ts +++ b/packages/core/src/routes/swagger/index.test.ts @@ -120,7 +120,7 @@ describe('GET /swagger.json', () => { get: { parameters: [ { - $ref: '#/components/parameters/mockId:root', + $ref: '#/components/parameters/mockId-root', }, { name: 'field', @@ -135,7 +135,7 @@ describe('GET /swagger.json', () => { get: { parameters: [ { - $ref: '#/components/parameters/mockId:root', + $ref: '#/components/parameters/mockId-root', }, { name: 'field', diff --git a/packages/core/src/routes/swagger/utils/parameters.ts b/packages/core/src/routes/swagger/utils/parameters.ts index f623780696a..206cdcfba27 100644 --- a/packages/core/src/routes/swagger/utils/parameters.ts +++ b/packages/core/src/routes/swagger/utils/parameters.ts @@ -48,7 +48,7 @@ type BuildParameters = { * For path parameters, this function will try to match reusable ID parameters: * * - If the parameter name is `id`, and the path is `/organizations/{id}/users`, the parameter - * `id` will be a reference to `#/components/parameters/organizationId:root`. + * `id` will be a reference to `#/components/parameters/organizationId-root`. * - If the parameter name ends with `Id`, and the path is `/organizations/{id}/users/{userId}`, * the parameter `userId` will be a reference to `#/components/parameters/userId`. * @@ -206,7 +206,7 @@ export const mergeParameters = (destination: unknown[], source: unknown[]) => { * type: 'string', * }, * }, - * 'organizationId:root': { + * 'organizationId-root': { * name: 'id', * // ... same as above * }, @@ -216,7 +216,7 @@ export const mergeParameters = (destination: unknown[], source: unknown[]) => { * @remarks * The root path component is the first path component in the path. For example, the root path * component of `/organizations/{id}/users` is `organizations`. Since the name of the parameter is - * same for all root path components, we need to add an additional key with the `:root` suffix to + * same for all root path components, we need to add an additional key with the `-root` suffix to * distinguish them. * * @param rootComponent The root path component in kebab case (`foo-bar`). From d51e839cdb5debedceb269e3911bce86064f5c8a Mon Sep 17 00:00:00 2001 From: Gao Sun Date: Sun, 23 Jun 2024 13:47:10 +0800 Subject: [PATCH 3/3] refactor: add changeset and improve code --- .changeset/heavy-badgers-jog.md | 8 ++++++++ packages/core/src/routes/swagger/index.ts | 3 +-- packages/core/src/routes/swagger/utils/parameters.ts | 7 +++---- 3 files changed, 12 insertions(+), 6 deletions(-) create mode 100644 .changeset/heavy-badgers-jog.md diff --git a/.changeset/heavy-badgers-jog.md b/.changeset/heavy-badgers-jog.md new file mode 100644 index 00000000000..e4764a07eb5 --- /dev/null +++ b/.changeset/heavy-badgers-jog.md @@ -0,0 +1,8 @@ +--- +"@logto/core": patch +--- + +fix OpenAPI schema returned by the `GET /api/swagger.json` endpoint + +1. The `:` character is invalid in parameter names, such as `organizationId:root`. These characters have been replaced with `-`. +2. The `tenantId` parameter of the `/api/.well-known/endpoints/{tenantId}` route was missing from the generated OpenAPI spec document, resulting in validation errors. This has been fixed. diff --git a/packages/core/src/routes/swagger/index.ts b/packages/core/src/routes/swagger/index.ts index a15c38e4ef7..cd3fd4b687e 100644 --- a/packages/core/src/routes/swagger/index.ts +++ b/packages/core/src/routes/swagger/index.ts @@ -236,9 +236,8 @@ export default function swaggerRoutes ({ ...previous, ...buildPathIdParameters(entityName), - ...customParameters(), }), - {} + customParameters() ), }, tags: [...tags, ...additionalTags].map((tag) => ({ name: tag })), diff --git a/packages/core/src/routes/swagger/utils/parameters.ts b/packages/core/src/routes/swagger/utils/parameters.ts index 206cdcfba27..a3bccbc509c 100644 --- a/packages/core/src/routes/swagger/utils/parameters.ts +++ b/packages/core/src/routes/swagger/utils/parameters.ts @@ -253,11 +253,10 @@ export const buildPathIdParameters = ( }; /** - * Build a parameter object for the `tenantId` parameter. - * @returns The parameter object for the `tenantId` parameter. + * Build a parameter object with additional parameters that are not inferred from the path. */ export const customParameters = (): Record => { - return { + return Object.freeze({ tenantId: { name: 'tenantId', in: 'path', @@ -267,5 +266,5 @@ export const customParameters = (): Record => type: 'string', }, }, - }; + }); };