Merge pull request #6089 from mostafa/fix-oas-validation-errors

fix: generate valid OpenAPI spec

.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.

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',

packages/core/src/routes/swagger/index.ts

@@ -35,6 +35,7 @@ import {
  paginationParameters,
  buildPathIdParameters,
  mergeParameters,
+ customParameters,
 } from './utils/parameters.js';
 
 type RouteObject = {
@@ -242,8 +243,11 @@ export default function swaggerRoutes<T extends AnonymousRouter, R extends Route
  components: {
  schemas: translationSchemas,
  parameters: identifiableEntityNames.reduce(
- (previous, entityName) => ({ ...previous, ...buildPathIdParameters(entityName) }),
- {}
+ (previous, entityName) => ({
+ ...previous,
+ ...buildPathIdParameters(entityName),
+ }),
+ customParameters()
  ),
  },
  tags: [...tags, ...additionalTags].map((tag) => ({ name: tag })),

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`.
  *
@@ -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`,
  };
  }
 
@@ -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`).
@@ -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,20 @@ export const buildPathIdParameters = (
  },
  };
 };
+
+/**
+ * Build a parameter object with additional parameters that are not inferred from the path.
+ */
+export const customParameters = (): Record<string, OpenAPIV3.ParameterObject> => {
+ return Object.freeze({
+ tenantId: {
+ name: 'tenantId',
+ in: 'path',
+ description: 'The unique identifier of the tenant.',
+ required: true,
+ schema: {
+ type: 'string',
+ },
+ },
+ });
+};