@fastify/swagger

@fastify/swagger is the official Fastify plugin that generates an OpenAPI (Swagger) specification from the route schemas already defined on your Fastify server, then exposes it as JSON/YAML — no separate annotation layer needed. It is the actively maintained, scoped successor to the original fastify-swagger npm package, which is deprecated in favor of this @fastify/*-namespaced release.

It supports both Swagger 2.0 and OpenAPI 3.x specs, works with any of Fastify’s supported schema validators (JSON Schema, TypeBox, Zod via fastify-type-provider-zod), and is typically paired with @fastify/swagger-ui to render an interactive documentation page.

What You Get

• Automatic OpenAPI 3.x / Swagger 2.0 spec generation from existing Fastify route schemas
• A /documentation/json and /documentation/yaml endpoint (configurable) exposing the generated spec
• Support for $ref resolution, shared schemas, and Fastify’s schema composition features in the generated spec
• Hooks for enriching generated operations with summary, description, tags, security, and other OpenAPI metadata
• Compatibility with TypeBox and Zod-based schema definitions via Fastify’s type-provider ecosystem
• Pairing with @fastify/swagger-ui to serve an interactive Swagger UI page from the same spec

Common Use Cases

• Publishing always-up-to-date API documentation for a Fastify service without maintaining a separate OpenAPI file by hand
• Generating a machine-readable OpenAPI spec that downstream tools (client generators, API gateways, contract tests) consume
• Serving an interactive Swagger UI so frontend or partner teams can explore and try out API endpoints
• Enforcing schema-first API design where the same JSON Schema drives both runtime validation and public documentation

Under The Hood

Architecture - The plugin hooks into Fastify’s route registration lifecycle: lib/spec/ builds the base OpenAPI/Swagger document object, lib/mode/ handles the two generation strategies (“dynamic”, generating the spec on first request, versus “static”, loading a pre-built spec), and lib/util/ resolves shared $ref schemas and normalizes route-level schema metadata into spec operations, all exposed through the small index.js entrypoint that registers the plugin’s decorators and routes. Tech Stack - Plain CommonJS JavaScript with type: commonjs in package.json, built on Fastify’s plugin encapsulation model (fastify-plugin), tested with Node’s built-in test runner plus c8 for 100%-enforced coverage and tstyche for TypeScript type-definition tests. Code Quality - The codebase enforces full test coverage (c8 --100) across unit and TypeScript typing tests, includes test-types/ for validating the published .d.ts types against real usage, and an examples/ directory demonstrating common integration patterns; the repo has 746 commits since 2017 with continuous recent activity and 100+ tagged releases. API Design - Because the plugin derives documentation entirely from schemas you already define for request/response validation, there is no second source of truth to keep in sync — registering the plugin and optionally attaching @fastify/swagger-ui is typically the entire integration surface, which keeps the API very low-friction for teams already using Fastify’s schema validation.