tekir
All Packages
Dev Toolsv0.1.7

@tekir/swagger

OpenAPI 3.0 spec builder and Swagger UI.

Installation

$bun add @tekir/swagger
DocumentationSource Code

Features

  • Auto-generates OpenAPI 3.0 spec from routes
  • Built-in Swagger UI served at configurable path
  • Optional HTTP Basic auth gating
  • Route decorators: @ApiTag, @ApiBody, @ApiResponse, @ApiParam
  • Zod-to-JSON-Schema conversion via zodToJsonSchema()
  • SwaggerProvider for automatic setup

Quick Example

TypeScript
import { swagger } from '@tekir/swagger'

swagger(router, {
  title: 'My API',
  version: '1.0.0',
  path: '/docs',
  auth: { username: 'admin', password: process.env.DOCS_PASSWORD! },
})

Changelog

v0.1.7LatestSeptember 16, 2026
  • OpenAPI route collection now includes domain-constrained handlers.
  • Published output now uses the shared Node-targeted ESM bundle pipeline with external dependencies and generated TypeScript declarations, while Bun consumers keep the native source export.
v0.1.6July 31, 2026
  • ApiParamOptions.schema and fluent apiParam(..., { schema }) now preserve complete OpenAPI parameter schemas, including enums, arrays, bounds, unions, and other JSON Schema keywords.
  • Legacy parameter options continue to emit type, format, example, and enum correctly.
v0.1.5July 23, 2026
  • Package metadata now follows the shared compatible 0.1.x dependency range used by the coordinated Tekir release.
v0.1.4June 13, 2026
  • Swagger docs are now gated by environment by default. Under NODE_ENV=production with no auth configured, the routes are not registered and a warning is logged. Use SwaggerConfig.enabled to force the docs on or off in either direction.
  • New @ApiHide() decorator plus SwaggerConfig.hidePaths (string prefix or RegExp) let you keep internal routes out of the generated spec.
  • Found and fixed with Fable.
v0.1.3May 17, 2026
  • Swagger UI assets now load from a pinned [email protected] URL with optional Subresource Integrity. The new ui.cssUrl, ui.jsUrl, ui.cssIntegrity, and ui.jsIntegrity config keys let apps self-host the bundle or pin SRI hashes that the browser enforces before executing the CDN payload.
  • The /docs HTML response now ships a strict Content-Security-Policy with no unsafe-inline. The only inline bootstrap is allowlisted via its SHA-256 hash, so any injected <script> is refused by the browser. The response also carries X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and Referrer-Policy: no-referrer.
  • jsonPath is now embedded into the bootstrap via JSON.stringify(...) plus </script escaping, so a custom config.path cannot break out of the inline script context.
  • Basic auth credential comparison now hashes both sides to fixed-length HMAC digests before timingSafeEqual(). Earlier releases short-circuited on length mismatch, which leaked the password length to attackers timing the response. The auth config surface is unchanged.
v0.1.2May 8, 2026
  • @ApiParam accepts an enum field on its options, matching the OpenAPI parameter spec: @ApiParam('status', { type: 'string', enum: ['active', 'inactive'] }) now type-checks and propagates into the generated spec.
  • buildOpenApiSpec(router, config) accepts null/undefined for the router argument. The runtime path already returned an empty paths object for falsy routers; the signature now matches the documented behaviour.
  • RouterLike.get is optional. Spec-only consumers (a plain trie wrapper, a test fixture, a CI script generating JSON) can satisfy the interface without supplying a handler-registration method; swagger() still requires it for live UI wiring.
v0.1.1April 29, 2026
  • Optional HTTP Basic auth on the Swagger UI and JSON spec. Pass auth: { username, password, realm? } to gate /docs, /docs/, and /docs/json. Constant-time credential comparison; sends a 401 with WWW-Authenticate: Basic realm="docs" when credentials are missing or wrong.
v0.1.0April 1, 2026
  • Initial release

Other Dev Tools packages

@tekir/clicreate-tekir-app@tekir/testing@tekir/health