feat: add operationId to HTTP methods on paths

.changeset/brown-cobras-know.md

@@ -0,0 +1,21 @@
+---
+"@logto/core": patch
+---
+
+build `operationId` for Management API in OpenAPI response (credit to @mostafa)
+
+As per [the specification](https://swagger.io/docs/specification/paths-and-operations/):
+
+> `operationId` is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.
+
+This greatly simplifies the creation of client SDKs in different languages, because it generates more meaningful function names instead of auto-generated ones, like the following examples:
+
+```diff
+- org, _, err := s.Client.OrganizationsAPI.ApiOrganizationsIdGet(ctx, req.GetId()).Execute()
++ org, _, err := s.Client.OrganizationsAPI.GetOrganization(ctx, req.GetId()).Execute()
+```
+
+```diff
+- users, _, err := s.Client.OrganizationsAPI.ApiOrganizationsIdUsersGet(ctx, req.GetId()).Execute()
++ users, _, err := s.Client.OrganizationsAPI.ListOrganizationUsers(ctx, req.GetId()).Execute()
+```

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

@@ -92,7 +92,7 @@ describe('GET /swagger.json', () => {
   it('should parse the path parameters', async () => {
     const queryParametersRouter = new Router();
     queryParametersRouter.get(
-      '/mock/:id/:field',
+      '/mock/:id/fields/:field',
       koaGuard({
         params: object({
           id: number(),
@@ -103,7 +103,7 @@ describe('GET /swagger.json', () => {
     );
     // Test plural
     queryParametersRouter.get(
-      '/mocks/:id/:field',
+      '/mocks/:id/fields/:field',
       koaGuard({
         params: object({
           id: number(),
@@ -116,7 +116,7 @@ describe('GET /swagger.json', () => {
 
     const response = await swaggerRequest.get('/swagger.json');
     expect(response.body.paths).toMatchObject({
-      '/api/mock/{id}/{field}': {
+      '/api/mock/{id}/fields/{field}': {
         get: {
           parameters: [
             {
@@ -131,7 +131,7 @@ describe('GET /swagger.json', () => {
           ],
         },
       },
-      '/api/mocks/{id}/{field}': {
+      '/api/mocks/{id}/fields/{field}': {
         get: {
           parameters: [
             {

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

@@ -28,9 +28,11 @@
   findSupplementFiles,
   normalizePath,
   removeUnnecessaryOperations,
+  shouldThrow,
   validateSupplement,
   validateSwaggerDocument,
 } from './utils/general.js';
+import { buildOperationId, customRoutes, throwByDifference } from './utils/operation-id.js';
 import {
   buildParameters,
   paginationParameters,
@@ -54,6 +56,7 @@
 };
 
 const buildOperation = (
+  method: OpenAPIV3.HttpMethods,
   stack: IMiddleware[],
   path: string,
   isAuthGuarded: boolean
@@ -111,6 +114,7 @@
   const [firstSegment] = path.split('/').slice(1);
 
   return {
+    operationId: buildOperationId(method, path),
     tags: [buildTag(path)],
     parameters: [...pathParameters, ...queryParameters],
     requestBody,
@@ -170,6 +174,12 @@
   allRouters: R[]
 ) {
   router.get('/swagger.json', async (ctx, next) => {
+    /**
+     * A set to store all custom routes that have been built.
+     * @see {@link customRoutes}
+     */
+    const builtCustomRoutes = new Set<string>();
+
     const routes = allRouters.flatMap<RouteObject>((router) => {
       const isAuthGuarded = isManagementApiRouter(router);
 
@@ -184,7 +194,11 @@
               .filter((method): method is OpenAPIV3.HttpMethods => method !== 'head')
               .map((httpMethod) => {
                 const path = normalizePath(routerPath);
-                const operation = buildOperation(stack, routerPath, isAuthGuarded);
+                const operation = buildOperation(httpMethod, stack, routerPath, isAuthGuarded);
+
+                if (customRoutes[`${httpMethod} ${routerPath}`]) {
+                  builtCustomRoutes.add(`${httpMethod} ${routerPath}`);
+                }
 
                 return {
                   path,
@@ -196,6 +210,9 @@
       );
     });
 
+    // Ensure all custom routes are built.
+    throwByDifference(builtCustomRoutes);
+
     const pathMap = new Map<string, OpenAPIV3.PathItemObject>();
     const tags = new Set<string>();
 
@@ -286,7 +303,7 @@
       getConsoleLogFromContext(ctx).warn('Skip validating swagger document in unit test.');
     }
     // Don't throw for integrity check in production as it has no benefit.
-    else if (!EnvSet.values.isProduction || EnvSet.values.isIntegrationTest) {
+    else if (shouldThrow()) {
       for (const document of supplementDocuments) {
         validateSupplement(baseDocument, document);
       }

packages/core/src/routes/swagger/utils/general.ts

@@ -262,3 +262,5 @@ export const removeUnnecessaryOperations = (
 
   return document;
 };
+
+export const shouldThrow = () => !EnvSet.values.isProduction || EnvSet.values.isIntegrationTest;

packages/core/src/routes/swagger/utils/operation-id.test.ts

@@ -0,0 +1,53 @@
+import { OpenAPIV3 } from 'openapi-types';
+
+import { buildOperationId, customRoutes } from './operation-id.js';
+
+describe('buildOperationId', () => {
+  it('should return the custom operation id if it exists', () => {
+    for (const [path, operationId] of Object.entries(customRoutes)) {
+      const [method, pathSegments] = path.split(' ');
+      expect(buildOperationId(method! as OpenAPIV3.HttpMethods, pathSegments!)).toBe(operationId);
+    }
+  });
+
+  it('should skip interactions APIs', () => {
+    expect(buildOperationId(OpenAPIV3.HttpMethods.GET, '/interaction/footballs')).toBeUndefined();
+  });
+
+  it('should handle JIT APIs', () => {
+    expect(buildOperationId(OpenAPIV3.HttpMethods.GET, '/footballs/:footballId/jit/bars')).toBe(
+      'ListFootballJitBars'
+    );
+  });
+
+  it('should throw if the path is invalid', () => {
+    expect(() =>
+      buildOperationId(OpenAPIV3.HttpMethods.GET, '/footballs/:footballId/bar/baz')
+    ).toThrow();
+    expect(() => buildOperationId(OpenAPIV3.HttpMethods.GET, '/')).toThrow();
+  });
+
+  it('should singularize the item for POST requests', () => {
+    expect(buildOperationId(OpenAPIV3.HttpMethods.POST, '/footballs/:footballId/bars')).toBe(
+      'CreateFootballBar'
+    );
+  });
+
+  it('should singularize for single item requests', () => {
+    expect(buildOperationId(OpenAPIV3.HttpMethods.DELETE, '/footballs/:footballId')).toBe(
+      'DeleteFootball'
+    );
+  });
+
+  it('should use "Get" if the last item is singular', () => {
+    expect(buildOperationId(OpenAPIV3.HttpMethods.GET, '/footballs/:footballId/bar')).toBe(
+      'GetFootballBar'
+    );
+  });
+
+  it('should use "List" if the last item is plural', () => {
+    expect(buildOperationId(OpenAPIV3.HttpMethods.GET, '/footballs/:footballId/bars')).toBe(
+      'ListFootballBars'
+    );
+  });
+});