Feat: add descriptions and extra responses to events endpoints.

src/lib/openapi/standard-responses.ts

@@ -0,0 +1,23 @@
+import { OpenAPIV3 } from 'openapi-types';
+
+export const unauthorizedResponse: OpenAPIV3.ResponseObject = {
+    description:
+        'Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.',
+} as const;
+
+const standardResponses = {
+    401: unauthorizedResponse,
+} as const;
+
+type StandardResponses = typeof standardResponses;
+
+export const getStandardResponses = <K extends keyof StandardResponses>(
+    ...statusCodes: K[]
+): OpenAPIV3.ResponsesObject =>
+    statusCodes.reduce(
+        (acc, n) => ({
+            ...acc,
+            [n]: standardResponses[String(n)] as OpenAPIV3.ResponseObject,
+        }),
+        {},
+    );

src/lib/routes/admin-api/event.ts

@@ -17,6 +17,7 @@ import {
     featureEventsSchema,
     FeatureEventsSchema,
 } from '../../../lib/openapi/spec/feature-events-schema';
+import { getStandardResponses } from '../../../lib/openapi/standard-responses';
 
 const version = 1;
 export default class EventController extends Controller {
@@ -48,8 +49,24 @@ export default class EventController extends Controller {
                     operationId: 'getEvents',
                     tags: ['admin'],
                     responses: {
+                        ...getStandardResponses(401),
                         200: createResponseSchema('eventsSchema'),
                     },
+
+                    parameters: [
+                        {
+                            name: 'project',
+                            description:
+                                'The name of the project whose events you want to retrieve',
+                            schema: { type: 'string' },
+                            in: 'query',
+                        },
+                    ],
+
+                    description:
+                        'Returns **the last 100** from the Unleash instance when called without a query parameter. When called with a `project` parameter, returns **all events** for the specified project.\n\nIf the provided project does not exist, the list of events will be empty.',
+                    summary:
+                        'Get the most recent events from the Unleash instance or all events related to a project.',
                 }),
             ],
         });
@@ -64,8 +81,13 @@ export default class EventController extends Controller {
                     operationId: 'getEventsForToggle',
                     tags: ['admin'],
                     responses: {
+                        ...getStandardResponses(401),
                         200: createResponseSchema('featureEventsSchema'),
                     },
+                    description:
+                        'Returns all events related to the specified feature toggle. If the feature toggle does not exist, the list of events will be empty.',
+                    summary:
+                        'Get all events related to a specific feature toggle.',
                 }),
             ],
         });