Add Swagger UI for OpenAPI human output

imports.d.ts

@@ -0,0 +1,4 @@
+declare module '*.css' {
+    const content: string;
+    export default content;
+}

package.json

@@ -42,6 +42,7 @@
         "react": "^19.2.5",
         "react-dom": "^19.2.5",
         "semver": "^7.7.4",
+        "swagger-ui-react": "^5.32.5",
         "zod": "^4.3.6"
     },
     "devDependencies": {
@@ -55,6 +56,7 @@
         "@types/react": "^19.2.14",
         "@types/react-dom": "^19.2.3",
         "@types/semver": "^7.7.1",
+        "@types/swagger-ui-react": "^5.18.0",
         "eslint": "^10.2.1",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-jsdoc": "^62.9.0",

src/routes/api.page.tsx

@@ -0,0 +1,11 @@
+import Swagger from '../utils/jsx/islands/swagger.tsx';
+
+import type { OpenApiResponse } from './api.schema.ts';
+
+/**
+ * /api page component.
+ *
+ * @param props Page props.
+ * @param props.data OpenAPI response data.
+ */
+export default ({ data }: { data: OpenApiResponse }) => <Swagger spec={data} />;

src/routes/api.ts

@@ -7,6 +7,7 @@ import * as z from 'zod';
 
 import respond, { withCache } from '../utils/respond.ts';
 
+import ApiPage from './api.page.tsx';
 import { type OpenApiResponse, openApiResponseSchema } from './api.schema.ts';
 import { errorResponseSchema } from './errors.schema.ts';
 
@@ -50,7 +51,16 @@ const createHandleGetApi = (registry: OpenAPIRegistry) => {
 
             definitions.sort((a, b) => {
                 if (a.type === 'route' && b.type === 'route') {
-                    // Sort by method first
+                    // Hoist routes with the libraries tag, as they are the core of cdnjs
+                    const aHasLibrariesTag =
+                        a.route.tags?.includes('libraries');
+                    const bHasLibrariesTag =
+                        b.route.tags?.includes('libraries');
+                    if (aHasLibrariesTag !== bHasLibrariesTag) {
+                        return aHasLibrariesTag ? -1 : 1;
+                    }
+
+                    // Otherwise, sort by method first
                     const methodOrder = [
                         'get',
                         'post',
@@ -99,6 +109,15 @@ const createHandleGetApi = (registry: OpenAPIRegistry) => {
             ) {
                 delete spec.components.parameters;
             }
+
+            // Sort the schemas in the components object alphabetically, for easier navigation by humans
+            if (spec.components?.schemas) {
+                spec.components.schemas = Object.fromEntries(
+                    Object.entries(spec.components.schemas).sort(([a], [b]) =>
+                        a.localeCompare(b),
+                    ),
+                );
+            }
         }
 
         return spec;
@@ -113,7 +132,7 @@ const createHandleGetApi = (registry: OpenAPIRegistry) => {
         // Set a 6 hour life on this response
         withCache(ctx, 6 * 60 * 60);
 
-        return respond<OpenApiResponse>(ctx, getOrGenerateSpec());
+        return respond<OpenApiResponse>(ctx, getOrGenerateSpec(), ApiPage);
     };
 
     return handleGetApi;

src/routes/libraries.schema.ts

@@ -4,12 +4,15 @@ import { librarySchema } from '../utils/algolia.schema';
 
 export const librariesResponseSchema = z.object({
     results: z.array(
-        librarySchema.partial().and(
-            z.object({
-                name: z.string(),
-                latest: z.string().nullable(),
-            }),
-        ),
+        librarySchema
+            .partial()
+            .and(
+                z.object({
+                    name: z.string(),
+                    latest: z.string().nullable(),
+                }),
+            )
+            .openapi('LibraryResult'),
     ),
     total: z.number(),
     available: z.number(),

src/routes/library.schema.ts

@@ -10,7 +10,8 @@ export const libraryVersionResponseSchema = z
         rawFiles: z.array(z.string()),
         sri: z.record(z.string(), z.string()),
     })
-    .partial();
+    .partial()
+    .openapi('LibraryVersion');
 
 export type LibraryVersionResponse = z.infer<
     typeof libraryVersionResponseSchema
@@ -30,6 +31,7 @@ export const libraryResponseSchema = librarySchema
             }),
         ),
     })
-    .partial();
+    .partial()
+    .openapi('Library');
 
 export type LibraryResponse = z.infer<typeof libraryResponseSchema>;

src/utils/jsx/island.tsx

@@ -1,3 +1,4 @@
+import { css } from '@emotion/css';
 import { env } from 'cloudflare:workers';
 import { type ComponentType, createContext, useContext, useId } from 'react';
 import * as z from 'zod';
@@ -46,6 +47,12 @@ const serializeProps = (props: object) =>
         .replaceAll('\u2028', '\\u2028')
         .replaceAll('\u2029', '\\u2029');
 
+const styles = {
+    island: css`
+        display: contents;
+    `,
+};
+
 /**
  * Server helper for rendering an island with serialized props and entrypoint script.
  *
@@ -80,7 +87,11 @@ const Island = <T extends object>({
 
     return (
         <>
-            <div data-island={name} data-island-props={propsScriptId}>
+            <div
+                className={styles.island}
+                data-island={name}
+                data-island-props={propsScriptId}
+            >
                 <Component {...props} />
             </div>