fastify-xswagger
fastify.xswagger.docs[key]
Per-doc instance accessor — properties and spec() method for each registered Swagger scope.
fastify.xswagger.docskey
fastify.xswagger.docs is a plain object keyed by a slug derived from each doc's prefix. Each value is a SwaggerDocInstance with metadata about the doc scope and a spec() method that returns the live OpenAPI spec object.
Key Derivation
The key is derived from the prefix at registration time:
| Prefix | Key |
|---|---|
/admin | admin |
/api | api |
/api/v1 | api_v1 |
/ | root |
Leading slash is removed; inner slashes become underscores.
Signature
fastify.xswagger.docs[key]: {
prefix: string;
access: 'public' | 'private';
title: string;
version: string;
uiPath: string;
specPath: string;
spec(): object | null;
}
Properties
| Property | Type | Description |
|---|---|---|
prefix | string | The route prefix this doc scope covers |
access | 'public' | 'private' | Access level (private = Basic Auth required) |
title | string | Title shown in the Swagger UI header |
version | string | API version shown in the spec info |
uiPath | string | Full URL path to the Swagger UI (e.g. /admin/documentation) |
specPath | string | Full URL path to the raw OpenAPI JSON (e.g. /admin/documentation/json) |
spec()
Returns the live OpenAPI spec object for this doc scope. The spec reflects all registered routes for this prefix at the time of the call. Only available after Fastify has finished booting (after fastify.listen() or fastify.ready()).
fastify.xswagger.docs[key].spec(): object | null
Returns null if called before the server is ready.
Examples
Access a doc instance after registration
await fastify.register(xSwagger, {
docs: [
{ prefix: "/api", access: "public", title: "Customer API", version: "2.0.0" },
{ prefix: "/admin", access: "private", title: "Admin API" },
],
auth: { username: "admin", password: process.env.DOCS_PASSWORD },
});
await fastify.ready();
const apiDoc = fastify.xswagger.docs.api;
console.log(apiDoc.uiPath); // '/api/documentation'
console.log(apiDoc.specPath); // '/api/documentation/json'
console.log(apiDoc.access); // 'public'
const adminDoc = fastify.xswagger.docs.admin;
console.log(adminDoc.version); // '1.0.0'
Serve the live spec from an API endpoint
fastify.get("/internal/openapi/:scope", async (request, reply) => {
const { scope } = request.params;
const doc = fastify.xswagger.docs[scope];
if (!doc) {
return reply.code(404).send({ error: `No doc scope: ${scope}` });
}
const spec = doc.spec();
if (!spec) {
return reply.code(503).send({ error: "Server not ready" });
}
return spec;
});
Validate all doc scopes on startup
fastify.addHook("onReady", async () => {
for (const [key, doc] of Object.entries(fastify.xswagger.docs)) {
const spec = doc.spec();
const pathCount = Object.keys(spec?.paths ?? {}).length;
fastify.log.info({ key, pathCount, uiPath: doc.uiPath }, "xSwagger scope ready");
}
});
See also
- fastify.xswagger.config — Plugin-level config summary
- fastify-xswagger overview — Plugin setup and options
AI Context
package: "@xenterprises/fastify-xswagger"
accessor: fastify.xswagger.docs[key]
use-when: Access per-doc instance metadata (uiPath, specPath, access, version) or retrieve the live OpenAPI spec object via spec() after server is ready
key-derivation: prefix → strip leading slash, replace inner slashes with underscores (e.g. "/api/v1" → "api_v1")
returns: { prefix, access, title, version, uiPath, specPath, spec() }