Skip to content

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

Open
MridulTailor wants to merge 1 commit intocdnjs:masterfrom
MridulTailor:openapi-endpoint-spec
Open

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

Conversation

@MridulTailor
Copy link
Copy Markdown
Contributor

Type of Change

  • Routes: Added /api endpoint in src/routes/api.ts returning an OpenAPI 3.0.0 specification as a plain TypeScript object. Integrated into src/index.ts.
  • 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.
  • Manually map response shapes from the existing Zod schemas (library.schema.ts, libraries.schema.ts) to OpenAPI JSON Schema format, avoiding any new runtime dependencies.
  • Correctly represent the autoupdate property using OpenAPI oneOf to reflect the z.union definition, enforcing type/target and source/target variants with their respective required fields.
  • Include required: ['name'] on library result items, honouring the .and({ name, latest }) Zod constraint.
  • 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 3.0.0 JSON object with descriptions matching the original cdnjs API documentation.
  • OpenAPI paths and component schemas accurately reflect the data returned by the existing endpoints.
  • No new runtime dependencies are introduced.
  • 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](https://developers.cloudflare.com/workers/testing/vitest-integration/known-issues/#module-resolution).

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