Skip to content

feat: add /api endpoint returning OpenAPI 3.0.0 specification#196

Open
MridulTailor wants to merge 2 commits intocdnjs:masterfrom
MridulTailor:openapi-endpoint-spec
Open

feat: add /api endpoint returning OpenAPI 3.0.0 specification#196
MridulTailor wants to merge 2 commits intocdnjs:masterfrom
MridulTailor:openapi-endpoint-spec

Conversation

@MridulTailor
Copy link
Copy Markdown
Contributor

@MridulTailor MridulTailor commented Apr 19, 2026

Type of Change

  • Routes: Added /api endpoint in src/routes/api.ts which returns an OpenAPI 3.0.0 specification dynamically generated from the existing Zod schemas using OpenAPIRegistry. Integrated into src/index.ts.
  • Utilities: Added src/utils/openapi.ts to globally initialize extendZodWithOpenApi(z).
  • Tests: Added src/routes/api.spec.ts with 7 tests covering CORS headers, cache headers, status codes, trailing slash resolution, and structural validation of the returned OpenAPI JSON spec.

What issue does this relate to?

Closes #189

What should this PR do?

  • Introduce a new /api endpoint that returns an OpenAPI 3.0.0 JSON specification for the cdnjs API.
  • Introduce @asteasolutions/zod-to-openapi as a dependency to dynamically generate the OpenAPI definitions directly from existing Zod schemas (library.schema.ts, libraries.schema.ts, etc.), ensuring response shapes are never manually duplicated and remain easily maintainable.
  • Ensure complex Zod constraints like unions (autoupdate property) and intersections (required: ['name']) are automatically parsed and translated to OpenAPI oneOf/allOf attributes by the library.
  • Include a path entry for /api itself and a servers block pointing to https://api.cdnjs.com.
  • Use a 6-hour cache (matching libraries.ts and stats.ts) rather than a long-lived immutable cache, keeping the spec updatable as the API evolves.

What are the acceptance criteria?

  • The /api endpoint returns a valid OpenAPI JSON object with descriptions matching the original cdnjs API documentation.
  • OpenAPI paths and component schemas dynamically and accurately reflect the data returned by the existing endpoints without needing manual mapping.
  • Types and lint pass with 0 errors (npm run types, npm run lint).
  • Note: The 7 new tests show as skipped due to a pre-existing semver CommonJS module resolution issue in @cloudflare/vitest-pool-workers that affects the entire test suite — unrelated to this PR. See Cloudflare Workers known issues.

Copy link
Copy Markdown
Member

@MattIPv4 MattIPv4 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this :)

Please can you generate the OpenAPI response schemas from the Zod schemas we define for each route -- this is not maintainable to have all the response types duplicated and written out manually.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add /api endpoint with OpenAPI spec

2 participants