docs: switch order of api doc sidebar items; put legacy docs under legacy header (#4135)

Also adds a caution admonition to the legacy doc index page

website/docs/reference/api/legacy/unleash/index.md

@@ -1,8 +1,14 @@
 ---
 id: index
-title: API Documentation
+title: Legacy API Documentation
 ---
 
+:::caution
+
+The docs in this category are legacy documentation. You should prefer to use the [Unleash OpenAPI docs](/reference/api/unleash) instead whenever possible.
+
+:::
+
 ## Client API {#client-api}
 
 This describes the API provided to unleash-clients.

website/sidebars.js

@@ -181,11 +181,28 @@ module.exports = {
                 },
                 {
                     type: 'category',
+                    label: 'APIs',
+                    items: [
+                        {
+                            label: 'OpenAPI docs',
+                            collapsed: true,
+                            type: 'category',
+                            link: {
+                                title: 'Unleash Server APIs',
+                                type: 'generated-index',
+                                description:
+                                    'Generated API docs based on the Unleash OpenAPI schema. For the time being, some additional info can also be found in the older API docs.',
+                                slug: '/reference/api/unleash',
+                            },
+                            items: require('./docs/reference/api/unleash/sidebar.js'),
+                        },
+                        {
+                            type: 'category',
+                            label: 'Legacy API docs',
                             link: {
                                 type: 'doc',
                                 id: 'reference/api/legacy/unleash/index',
                             },
-                    label: 'APIs',
                             items: [
                                 {
                                     'Admin API': [
@@ -214,18 +231,7 @@ module.exports = {
                                         'reference/api/legacy/unleash/internal/health',
                                     ],
                                 },
-                        {
+                            ],
-                            label: 'OpenAPI docs',
-                            collapsed: true,
-                            type: 'category',
-                            link: {
-                                title: 'Unleash Server APIs',
-                                type: 'generated-index',
-                                description:
-                                    'Generated API docs based on the Unleash OpenAPI schema. For the time being, some additional info can also be found in the older API docs.',
-                                slug: '/reference/api/unleash',
-                            },
-                            items: require('./docs/reference/api/unleash/sidebar.js'),
                         },
                     ],
                 },