Skip to content

chore(docs): fetch OpenAPI spec from cloudflare/api-schemas #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
teamchong merged 1 commit into from
Nov 4, 2026
Merged

chore(docs): fetch OpenAPI spec from cloudflare/api-schemas #89

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions packages/cloudflare-api-site/src/openapi-source.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,21 @@ import assert from 'node:assert/strict';
import { test } from 'node:test';
import { fetchForgeOpenApi, forgeOpenApiUrl, loadForgeOpenApi } from './openapi-source.ts';

test('uses the latest Forge OpenAPI release by default', () => {
test('uses the latest cloudflare/api-schemas main spec by default', () => {
assert.equal(
forgeOpenApiUrl(undefined).href,
'https://github.com/cloudflare/forge/releases/latest/download/openapi.forge.json',
'https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.json',
);
});

test('uses an exact encoded Forge OpenAPI release when pinned', () => {
test('uses an exact cloudflare/api-schemas revision when pinned', () => {
assert.equal(
forgeOpenApiUrl('openapi@8c827d1b18fec9aa686debf894580f0b302f6f94').href,
'https://github.com/cloudflare/forge/releases/download/openapi%408c827d1b18fec9aa686debf894580f0b302f6f94/openapi.forge.json',
'https://raw.githubusercontent.com/cloudflare/api-schemas/8c827d1b18fec9aa686debf894580f0b302f6f94/openapi.json',
);
});

test('fetches and parses the Forge OpenAPI release asset', async () => {
test('fetches and parses the Forge OpenAPI asset', async () => {
let requestedUrl: string | undefined;
const fetcher = async (input: string | URL | Request) => {
requestedUrl = String(input);
Expand All @@ -25,20 +25,20 @@ test('fetches and parses the Forge OpenAPI release asset', async () => {

const document = await fetchForgeOpenApi('openapi@test', fetcher);

assert.equal(requestedUrl, 'https://github.com/cloudflare/forge/releases/download/openapi%40test/openapi.forge.json');
assert.equal(requestedUrl, 'https://raw.githubusercontent.com/cloudflare/api-schemas/test/openapi.json');
assert.deepEqual(document, { openapi: '3.0.3' });
});

test('reports release asset download failures', async () => {
const fetcher = async () => new Response(null, { status: 404, statusText: 'Not Found' });

await assert.rejects(() => fetchForgeOpenApi('missing', fetcher), /404 Not Found.*openapi\.forge\.json/);
await assert.rejects(() => fetchForgeOpenApi('missing', fetcher), /404 Not Found.*openapi\.json/);
});

test('reports malformed release assets', async () => {
const fetcher = async () => new Response('{', { headers: { 'content-type': 'application/json' } });

await assert.rejects(() => fetchForgeOpenApi('malformed', fetcher), /Could not parse.*openapi\.forge\.json/);
await assert.rejects(() => fetchForgeOpenApi('malformed', fetcher), /Could not parse.*openapi\.json/);
});

test('loads an already-downloaded Forge OpenAPI artifact', async () => {
Expand Down
11 changes: 4 additions & 7 deletions packages/cloudflare-api-site/src/openapi-source.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { readFile } from 'node:fs/promises';

const FORGE_RELEASES_URL = new URL('https://github.com/cloudflare/forge/releases/');
const FORGE_OPENAPI_ASSET = 'openapi.forge.json';
const API_SCHEMAS_RAW_URL = new URL('https://raw.githubusercontent.com/cloudflare/api-schemas/');
const FORGE_OPENAPI_ASSET = 'openapi.json';

function parseForgeOpenApi(source: string, location: string): unknown {
try {
Expand All @@ -12,11 +12,8 @@ function parseForgeOpenApi(source: string, location: string): unknown {
}

export function forgeOpenApiUrl(release = process.env['FORGE_OPENAPI_RELEASE']): URL {
const revision = release?.trim();
const assetPath = revision
? `download/${encodeURIComponent(revision)}/${FORGE_OPENAPI_ASSET}`
: `latest/download/${FORGE_OPENAPI_ASSET}`;
return new URL(assetPath, FORGE_RELEASES_URL);
const revision = release?.trim().replace(/^openapi@/, '') || 'main';
return new URL(`${encodeURIComponent(revision)}/${FORGE_OPENAPI_ASSET}`, API_SCHEMAS_RAW_URL);
}

export async function fetchForgeOpenApi(
Expand Down
Loading