Add /api endpoint returning OpenAPI 3.0.0 specification

package.json

@@ -31,6 +31,7 @@
         "node": ">=24.11.0"
     },
     "dependencies": {
+        "@asteasolutions/zod-to-openapi": "^8.5.0",
         "@emotion/css": "^11.13.5",
         "@sentry/cloudflare": "^10.46.0",
         "algoliasearch": "^5.50.0",

src/index.ts

@@ -4,6 +4,9 @@ import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { logger } from 'hono/logger';
 
+import './utils/openapi.ts';
+
+import apiRoutes from './routes/api.ts';
 import errorRoutes from './routes/errors.ts';
 import indexRoutes from './routes/index.ts';
 import librariesRoutes from './routes/libraries.ts';
@@ -19,6 +22,7 @@ app.use('*', cors(corsOptions));
 
 // Load the routes
 indexRoutes(app);
+apiRoutes(app);
 statsRoutes(app);
 whitelistRoutes(app);
 libraryRoutes(app);

src/routes/api.schema.ts

@@ -0,0 +1,29 @@
+import * as z from 'zod';
+
+export const openApiResponseSchema = z.object({
+    openapi: z.string(),
+    info: z.object({
+        title: z.string(),
+        description: z.string().optional(),
+        version: z.string(),
+    }),
+    servers: z
+        .array(
+            z.object({
+                url: z.string(),
+                description: z.string().optional(),
+            }),
+        )
+        .optional(),
+    paths: z.record(z.string(), z.unknown()).openapi({ type: 'object' }),
+    components: z
+        .object({
+            schemas: z
+                .record(z.string(), z.unknown())
+                .openapi({ type: 'object' })
+                .optional(),
+        })
+        .optional(),
+});
+
+export type OpenApiResponse = z.infer<typeof openApiResponseSchema>;

src/routes/api.spec.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+
+import testCors from '../utils/spec/cors.ts';
+import { beforeRequest, request } from '../utils/spec/request.ts';
+
+import type { OpenApiResponse } from './api.schema.ts';
+
+describe('/api', () => {
+    // Fetch the endpoint
+    const path = '/api';
+    const response = beforeRequest(path);
+
+    // Test the endpoint
+    testCors(path, response);
+    it('returns the correct Cache headers', () => {
+        expect(response.headers.get('Cache-Control')).to.eq(
+            'public, max-age=21600',
+        ); // 6 hours
+    });
+    it('returns the correct status code', () => {
+        expect(response.status).to.eq(200);
+    });
+    it('returns a valid OpenAPI spec in JSON format', async () => {
+        expect(response.headers.get('Content-Type')).to.match(
+            /application\/json/,
+        );
+        const data = await response.json<OpenApiResponse>();
+        expect(data.openapi).to.eq('3.0.0');
+        expect(data.info.title).to.eq('cdnjs API');
+        expect(data.paths['/libraries']).to.be.an('object');
+        expect(data.paths['/libraries/{library}']).to.be.an('object');
+        expect(data.components?.schemas?.Error).to.be.an('object');
+    });
+
+    // Test with a trailing slash
+    it('responds to requests with a trailing slash', async () => {
+        const res = await request(path + '/');
+        expect(res.status).to.eq(200);
+        const resData = await res.json();
+        const responseData = await response.json();
+        expect(resData).to.deep.eq(responseData);
+    });
+});