openapi: sort tags file (#4595)

This change sorts the tags in the tags file and tests that the list is
sorted alphabetically. This makes it easier to
find tags in the file. 

#4580 already introduced a test to check that we have no duplicate
tags, so this isn't as necessary anymore, but it's still nice to have.

It also removes the previous auto-sorting before exporting. This is to
ensure that entries are sorted in the source list. This might seem like
a regression, but it makes it easier to spot near-duplicate tags:

> Despite having the test that validates there are no duplicates, you
can always have Notifications and Notification API by mistake (tags that
mean the same but are different). Keeping the list alphabetically sorted
might help to prevent this before pushing the change to prod. In this
case, we will eventually find out and fix it, so this could be a good
reason to have the list sorted.

src/lib/openapi/util/openapi-tags.test.ts

@@ -6,3 +6,10 @@ test('no duplicate tags', () => {
         return [...acc, tag.name];
     }, []);
 });
+
+test('The list of OpenAPI tags is sorted', () => {
+    const tags = openApiTags.map((tag) => tag.name);
+    const sorted = [...tags].sort((a, b) => a.localeCompare(b));
+
+    expect(tags).toStrictEqual(sorted);
+});

src/lib/openapi/util/openapi-tags.ts

@@ -1,6 +1,7 @@
 // The "official" OpenAPI tags that we use. These tags are added to the OpenAPI
 // spec as the root-level "tags" list. Consider creating a new entry here when
-// creating a new endpoint.
+// creating a new endpoint. This list should always be sorted alphabetically on
+// the tag name.
 const OPENAPI_TAGS = [
     {
         name: 'Addons',
@@ -17,22 +18,17 @@ const OPENAPI_TAGS = [
         description:
             'Create, update, and delete [Unleash API tokens](https://docs.getunleash.io/reference/api-tokens-and-client-keys).',
     },
-    {
-        name: 'Personal access tokens',
-        description:
-            'Create, update, and delete [Personal access tokens](https://docs.getunleash.io/reference/api-tokens-and-client-keys#personal-access-tokens).',
-    },
-    {
-        name: 'Service Accounts',
-        description:
-            'Endpoints for managing [Service Accounts](https://docs.getunleash.io/reference/service-accounts), which enable programmatic access to the Unleash API.',
-    },
     {
         name: 'Archive',
         description:
             'Revive or permanently delete [archived feature toggles](https://docs.getunleash.io/advanced/archived_toggles).',
     },
     { name: 'Auth', description: 'Manage logins, passwords, etc.' },
+    {
+        name: 'Change Requests',
+        description:
+            'API for managing [change requests](https://docs.getunleash.io/reference/change-requests).',
+    },
     {
         name: 'Client',
         description:
@@ -43,21 +39,27 @@ const OPENAPI_TAGS = [
         description:
             'Create, update, and delete [context fields](https://docs.getunleash.io/reference/unleash-context) that Unleash is aware of.',
     },
+    { name: 'Edge', description: 'Endpoints related to Unleash on the Edge.' },
     {
         name: 'Environments',
         description:
             'Create, update, delete, enable or disable [environments](https://docs.getunleash.io/reference/environments) for this Unleash instance.',
     },
     { name: 'Events', description: 'Read events from this Unleash instance.' },
+    {
+        name: 'Feature Types',
+        description:
+            'Manage [feature toggle types](https://docs.getunleash.io/reference/feature-toggle-types).',
+    },
     {
         name: 'Features',
         description:
             'Create, update, and delete [features toggles](https://docs.getunleash.io/reference/feature-toggles).',
     },
     {
-        name: 'Feature Types',
+        name: 'Frontend API',
         description:
-            'Manage [feature toggle types](https://docs.getunleash.io/reference/feature-toggle-types).',
+            'API for connecting client-side (frontend) applications to Unleash.',
     },
     {
         name: 'Import/Export',
@@ -69,15 +71,29 @@ const OPENAPI_TAGS = [
         description:
             'Instance admin endpoints used to manage the Unleash instance itself.',
     },
+    {
+        name: 'Maintenance',
+        description: 'Enable/disable the maintenance mode of Unleash.',
+    },
     {
         name: 'Metrics',
         description: 'Register, read, or delete metrics recorded by Unleash.',
     },
+    {
+        name: 'Notifications',
+        description:
+            'API for managing [notifications](https://docs.getunleash.io/reference/notifications).',
+    },
     {
         name: 'Operational',
         description:
             'Endpoints related to the operational status of this Unleash instance.',
     },
+    {
+        name: 'Personal access tokens',
+        description:
+            'Create, update, and delete [Personal access tokens](https://docs.getunleash.io/reference/api-tokens-and-client-keys#personal-access-tokens).',
+    },
     {
         name: 'Playground',
         description:
@@ -98,6 +114,11 @@ const OPENAPI_TAGS = [
         description:
             'Create, update, delete, and manage [segments](https://docs.getunleash.io/reference/segments).',
     },
+    {
+        name: 'Service Accounts',
+        description:
+            'Endpoints for managing [Service Accounts](https://docs.getunleash.io/reference/service-accounts), which enable programmatic access to the Unleash API.',
+    },
     {
         name: 'Strategies',
         description:
@@ -108,42 +129,20 @@ const OPENAPI_TAGS = [
         description:
             'Create, update, and delete [tags and tag types](https://docs.getunleash.io/reference/tags).',
     },
-    { name: 'Users', description: 'Manage users and passwords.' },
-    {
-        name: 'Unstable',
-        description:
-            'Experimental endpoints that may change or disappear at any time.',
-    },
-    { name: 'Edge', description: 'Endpoints related to Unleash on the Edge.' },
-    {
-        name: 'Frontend API',
-        description:
-            'API for connecting client-side (frontend) applications to Unleash.',
-    },
-    {
-        name: 'Maintenance',
-        description: 'Enable/disable the maintenance mode of Unleash.',
-    },
-    {
-        name: 'Change Requests',
-        description:
-            'API for managing [change requests](https://docs.getunleash.io/reference/change-requests).',
-    },
     {
         name: 'Telemetry',
         description: 'API for information about telemetry collection',
     },
     {
-        name: 'Notifications',
+        name: 'Unstable',
         description:
-            'API for managing [notifications](https://docs.getunleash.io/reference/notifications).',
+            'Experimental endpoints that may change or disappear at any time.',
     },
+    { name: 'Users', description: 'Manage users and passwords.' },
 ] as const;
 
 // make the export mutable, so it can be used in a schema
-export const openApiTags = [...OPENAPI_TAGS].sort((a, b) =>
-    a.name.localeCompare(b.name),
-);
+export const openApiTags = [...OPENAPI_TAGS];
 
 export type OpenApiTag =
     // The official OpenAPI tags that we use.