@navios/openapi-fastify 0.7.0

package/lib/index.d.mts

@@ -0,0 +1,214 @@
+import { ApiDeprecated, ApiDeprecatedOptions, ApiExclude, ApiOperation, ApiOperationOptions, ApiSecurity, ApiSecurityRequirement, ApiStream, ApiStreamOptions, ApiSummary, ApiTag, ApiTagOptions, OpenApiEndpointMetadata, OpenApiGeneratorOptions, OpenApiGeneratorOptions as OpenApiGeneratorOptions$1 } from "@navios/openapi";
+import { z } from "zod";
+import { NaviosPlugin, PluginContext, PluginDefinition } from "@navios/core";
+
+//#region src/schemas/openapi-fastify-options.schema.d.mts
+/**
+ * Zod schema for Scalar UI theme options
+ */
+declare const scalarThemeSchema: z.ZodEnum<{
+  default: "default";
+  alternate: "alternate";
+  moon: "moon";
+  purple: "purple";
+  solarized: "solarized";
+  bluePlanet: "bluePlanet";
+  saturn: "saturn";
+  kepler: "kepler";
+  mars: "mars";
+  deepSpace: "deepSpace";
+  laserwave: "laserwave";
+  elysiajs: "elysiajs";
+  fastify: "fastify";
+  none: "none";
+}>;
+/**
+ * Zod schema for Scalar UI metadata
+ */
+declare const scalarMetaDataSchema: z.ZodOptional<z.ZodObject<{
+  title: z.ZodOptional<z.ZodString>;
+  description: z.ZodOptional<z.ZodString>;
+  ogDescription: z.ZodOptional<z.ZodString>;
+  ogTitle: z.ZodOptional<z.ZodString>;
+  ogImage: z.ZodOptional<z.ZodString>;
+  twitterCard: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/**
+ * Zod schema for Scalar UI configuration options
+ */
+declare const scalarOptionsSchema: z.ZodObject<{
+  theme: z.ZodOptional<z.ZodEnum<{
+    default: "default";
+    alternate: "alternate";
+    moon: "moon";
+    purple: "purple";
+    solarized: "solarized";
+    bluePlanet: "bluePlanet";
+    saturn: "saturn";
+    kepler: "kepler";
+    mars: "mars";
+    deepSpace: "deepSpace";
+    laserwave: "laserwave";
+    elysiajs: "elysiajs";
+    fastify: "fastify";
+    none: "none";
+  }>>;
+  favicon: z.ZodOptional<z.ZodString>;
+  logo: z.ZodOptional<z.ZodString>;
+  hideDownloadButton: z.ZodOptional<z.ZodBoolean>;
+  hideSearch: z.ZodOptional<z.ZodBoolean>;
+  customCss: z.ZodOptional<z.ZodString>;
+  metaData: z.ZodOptional<z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    ogDescription: z.ZodOptional<z.ZodString>;
+    ogTitle: z.ZodOptional<z.ZodString>;
+    ogImage: z.ZodOptional<z.ZodString>;
+    twitterCard: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  cdn: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Zod schema for Fastify OpenAPI plugin options
+ */
+declare const fastifyOpenApiPluginOptionsSchema: z.ZodObject<{
+  jsonPath: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+  yamlPath: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+  docsPath: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+  scalar: z.ZodOptional<z.ZodObject<{
+    theme: z.ZodOptional<z.ZodEnum<{
+      default: "default";
+      alternate: "alternate";
+      moon: "moon";
+      purple: "purple";
+      solarized: "solarized";
+      bluePlanet: "bluePlanet";
+      saturn: "saturn";
+      kepler: "kepler";
+      mars: "mars";
+      deepSpace: "deepSpace";
+      laserwave: "laserwave";
+      elysiajs: "elysiajs";
+      fastify: "fastify";
+      none: "none";
+    }>>;
+    favicon: z.ZodOptional<z.ZodString>;
+    logo: z.ZodOptional<z.ZodString>;
+    hideDownloadButton: z.ZodOptional<z.ZodBoolean>;
+    hideSearch: z.ZodOptional<z.ZodBoolean>;
+    customCss: z.ZodOptional<z.ZodString>;
+    metaData: z.ZodOptional<z.ZodObject<{
+      title: z.ZodOptional<z.ZodString>;
+      description: z.ZodOptional<z.ZodString>;
+      ogDescription: z.ZodOptional<z.ZodString>;
+      ogTitle: z.ZodOptional<z.ZodString>;
+      ogImage: z.ZodOptional<z.ZodString>;
+      twitterCard: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    cdn: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  disableScalar: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+  disableYaml: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+type ScalarTheme = z.infer<typeof scalarThemeSchema>;
+type ScalarOptions = z.infer<typeof scalarOptionsSchema>;
+type FastifyOpenApiPluginOptionsBase = z.infer<typeof fastifyOpenApiPluginOptionsSchema>;
+//#endregion
+//#region src/openapi-fastify.plugin.d.mts
+/**
+ * Combined options for the Fastify OpenAPI plugin.
+ * Extends OpenApiGeneratorOptions with Fastify-specific settings.
+ */
+interface FastifyOpenApiPluginOptions extends OpenApiGeneratorOptions$1, Partial<FastifyOpenApiPluginOptionsBase> {}
+/**
+ * Class-based OpenAPI Fastify plugin that integrates with Navios plugin system.
+ *
+ * This plugin:
+ * - Scans all registered modules for endpoints
+ * - Generates an OpenAPI 3.1 document
+ * - Serves the document as JSON and optionally YAML
+ * - Provides Scalar UI for interactive documentation
+ */
+declare class OpenApiFastifyPlugin implements NaviosPlugin<FastifyOpenApiPluginOptions> {
+  readonly name = "openapi-fastify";
+  register(context: PluginContext, options: FastifyOpenApiPluginOptions): Promise<void>;
+  /**
+   * Generates the Scalar API Reference HTML document.
+   *
+   * @param specUrl - URL to the OpenAPI JSON specification
+   * @param options - Scalar UI configuration options
+   * @returns Complete HTML document string
+   */
+  private generateScalarHtml;
+}
+/**
+ * Creates a plugin definition for the OpenAPI Fastify plugin.
+ *
+ * @param options - Plugin configuration options
+ * @returns Plugin definition to pass to `app.usePlugin()`
+ *
+ * @example
+ * ```typescript
+ * import { NaviosFactory } from '@navios/core'
+ * import { defineFastifyEnvironment } from '@navios/adapter-fastify'
+ * import { defineOpenApiPlugin } from '@navios/openapi-fastify'
+ *
+ * const app = await NaviosFactory.create(AppModule, {
+ *   adapter: defineFastifyEnvironment(),
+ * })
+ *
+ * app.usePlugin(defineOpenApiPlugin({
+ *   info: {
+ *     title: 'My API',
+ *     version: '1.0.0',
+ *     description: 'API documentation',
+ *   },
+ *   servers: [
+ *     { url: 'http://localhost:3000', description: 'Development' },
+ *   ],
+ *   securitySchemes: {
+ *     bearerAuth: {
+ *       type: 'http',
+ *       scheme: 'bearer',
+ *       bearerFormat: 'JWT',
+ *     },
+ *   },
+ *   scalar: {
+ *     theme: 'purple',
+ *   },
+ * }))
+ *
+ * await app.listen({ port: 3000 })
+ * // API docs available at http://localhost:3000/docs
+ * ```
+ */
+declare function defineOpenApiPlugin(options: FastifyOpenApiPluginOptions): PluginDefinition<FastifyOpenApiPluginOptions>;
+//#endregion
+//#region src/utils/apply-global-prefix.util.d.mts
+/**
+ * OpenAPI document shape (minimal interface for typing)
+ */
+interface OpenAPIDocument {
+  openapi: string;
+  info: {
+    title: string;
+    version: string;
+  };
+  paths?: Record<string, unknown>;
+  servers?: Array<{
+    url: string;
+    description?: string;
+  }>;
+}
+/**
+ * Applies global prefix to OpenAPI servers if needed.
+ *
+ * @param document - The OpenAPI document to modify
+ * @param globalPrefix - The global route prefix (e.g., '/api/v1')
+ * @param options - Plugin options that may contain server configuration
+ * @returns The document with servers array updated if applicable
+ */
+declare function applyGlobalPrefix<T extends OpenAPIDocument>(document: T, globalPrefix: string, options: OpenApiGeneratorOptions$1): T;
+//#endregion
+export { ApiDeprecated, type ApiDeprecatedOptions, ApiExclude, ApiOperation, type ApiOperationOptions, ApiSecurity, type ApiSecurityRequirement, ApiStream, type ApiStreamOptions, ApiSummary, ApiTag, type ApiTagOptions, type FastifyOpenApiPluginOptions, type OpenApiEndpointMetadata, OpenApiFastifyPlugin, type OpenApiGeneratorOptions, type ScalarOptions, type ScalarTheme, applyGlobalPrefix, defineOpenApiPlugin, fastifyOpenApiPluginOptionsSchema, scalarMetaDataSchema, scalarOptionsSchema, scalarThemeSchema };
+//# sourceMappingURL=index.d.mts.map

package/lib/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/schemas/openapi-fastify-options.schema.mts","../src/openapi-fastify.plugin.mts","../src/utils/apply-global-prefix.util.mts"],"sourcesContent":[],"mappings":";;;;;;;;cAKa,mBAAiB,CAAA,CAAA;EAAjB,OAAA,EAAA,SAAA;EAoBA,SAAA,EAAA,WAAA;;;;;;;;;;;;;;;;;AAcA,cAdA,oBA0DX,EA1D+B,CAAA,CAAA,WA0D/B,CA1D+B,CAAA,CAAA,SA0D/B,CAAA;;;;;;;;;;;cA5CW,qBAAmB,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;EAAA,UAAA,eAAA,aAAA,CAAA;EAAA,SAAA,eAAA,YAAA,CAAA;EAiDnB,QAAA,eAAA,YAAA,CAmCX;;;;;;;;;;;;;cAnCW,mCAAiC,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAA,aAAA,cAAA,cAAA,aAAA,CAAA,CAAA;EAAA,WAAA,cAAA,cAAA,aAAA,CAAA,CAAA;AAqC9C,CAAA,eAAY,CAAA;AAEA,KAFA,WAAA,GAAc,CAAA,CAAE,KAEe,CAAA,OAFF,iBAEX,CAAA;KAAlB,aAAA,GAAgB,CAAA,CAAE,aAAa;KAC/B,+BAAA,GAAkC,CAAA,CAAE,aAAa;;;;;AA3H7D;AAoBA;UCCiB,2BAAA,SACP,2BAAyB,QAAQ;;;;;;;;;;cAW9B,oBAAA,YAAgC,aAAa;;EDbzB,QAAA,CAAA,OAAA,ECiBpB,aDjBoB,EAAA,OAAA,ECkBpB,2BDlBoB,CAAA,ECmB5B,ODnB4B,CAAA,IAAA,CAAA;EAAA;;AAcjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA;;;;;;;;;;;;;;;iBCoEgB,mBAAA,UACL,8BACR,iBAAiB;;;;;;UCzJH,eAAA;EFAJ,OAAA,EAAA,MAAA;EAoBA,IAAA,EAAA;;;;UEdH;YACE;;;;;;;;;;;;AF2BZ;iBEbgB,4BAA4B,2BAChC,kCAED,4BACR"}

package/lib/index.mjs

@@ -0,0 +1,185 @@
+import { ApiDeprecated, ApiExclude, ApiOperation, ApiSecurity, ApiStream, ApiSummary, ApiTag, OpenApiGeneratorService } from "@navios/openapi";
+import { getHtmlDocument } from "@scalar/core/libs/html-rendering";
+import { stringify } from "yaml";
+import { z } from "zod";
+
+//#region src/schemas/openapi-fastify-options.schema.mts
+/**
+* Zod schema for Scalar UI theme options
+*/ const scalarThemeSchema = z.enum([
+	"default",
+	"alternate",
+	"moon",
+	"purple",
+	"solarized",
+	"bluePlanet",
+	"saturn",
+	"kepler",
+	"mars",
+	"deepSpace",
+	"laserwave",
+	"elysiajs",
+	"fastify",
+	"none"
+]);
+/**
+* Zod schema for Scalar UI metadata
+*/ const scalarMetaDataSchema = z.object({
+	title: z.string().optional(),
+	description: z.string().optional(),
+	ogDescription: z.string().optional(),
+	ogTitle: z.string().optional(),
+	ogImage: z.string().optional(),
+	twitterCard: z.string().optional()
+}).optional();
+/**
+* Zod schema for Scalar UI configuration options
+*/ const scalarOptionsSchema = z.object({
+	theme: scalarThemeSchema.optional(),
+	favicon: z.string().optional(),
+	logo: z.string().optional(),
+	hideDownloadButton: z.boolean().optional(),
+	hideSearch: z.boolean().optional(),
+	customCss: z.string().optional(),
+	metaData: scalarMetaDataSchema,
+	cdn: z.string().optional()
+});
+/**
+* Zod schema for Fastify OpenAPI plugin options
+*/ const fastifyOpenApiPluginOptionsSchema = z.object({
+	jsonPath: z.string().optional().default("/openapi.json"),
+	yamlPath: z.string().optional().default("/openapi.yaml"),
+	docsPath: z.string().optional().default("/docs"),
+	scalar: scalarOptionsSchema.optional(),
+	disableScalar: z.boolean().optional().default(false),
+	disableYaml: z.boolean().optional().default(true)
+});
+
+//#endregion
+//#region src/utils/apply-global-prefix.util.mts
+/**
+* Applies global prefix to OpenAPI servers if needed.
+*
+* @param document - The OpenAPI document to modify
+* @param globalPrefix - The global route prefix (e.g., '/api/v1')
+* @param options - Plugin options that may contain server configuration
+* @returns The document with servers array updated if applicable
+*/ function applyGlobalPrefix(document, globalPrefix, options) {
+	if (options.servers && options.servers.length > 0) return document;
+	if (!globalPrefix) return document;
+	return {
+		...document,
+		servers: [{
+			url: globalPrefix,
+			description: "API with global prefix"
+		}]
+	};
+}
+
+//#endregion
+//#region src/openapi-fastify.plugin.mts
+/**
+* Class-based OpenAPI Fastify plugin that integrates with Navios plugin system.
+*
+* This plugin:
+* - Scans all registered modules for endpoints
+* - Generates an OpenAPI 3.1 document
+* - Serves the document as JSON and optionally YAML
+* - Provides Scalar UI for interactive documentation
+*/ var OpenApiFastifyPlugin = class {
+	name = "openapi-fastify";
+	async register(context, options) {
+		const fastify = context.server;
+		const parsedOptions = fastifyOpenApiPluginOptionsSchema.parse(options);
+		const documentWithServers = applyGlobalPrefix((await context.container.get(OpenApiGeneratorService)).generate(context.modules, options), context.globalPrefix, options);
+		const jsonPath = parsedOptions.jsonPath;
+		fastify.get(jsonPath, async (_request, reply) => {
+			return reply.send(documentWithServers);
+		});
+		if (!parsedOptions.disableYaml) {
+			const yamlPath = parsedOptions.yamlPath;
+			fastify.get(yamlPath, async (_request, reply) => {
+				reply.type("text/yaml");
+				return reply.send(stringify(documentWithServers));
+			});
+		}
+		if (!parsedOptions.disableScalar) {
+			const docsPath = parsedOptions.docsPath;
+			const scalarOptions = options.scalar ?? {};
+			const html = this.generateScalarHtml(jsonPath, scalarOptions);
+			fastify.get(docsPath, async (_request, reply) => {
+				reply.type("text/html");
+				return reply.send(html);
+			});
+		}
+	}
+	/**
+	* Generates the Scalar API Reference HTML document.
+	*
+	* @param specUrl - URL to the OpenAPI JSON specification
+	* @param options - Scalar UI configuration options
+	* @returns Complete HTML document string
+	*/ generateScalarHtml(specUrl, options) {
+		return getHtmlDocument({
+			url: specUrl,
+			theme: options.theme ?? "default",
+			favicon: options.favicon,
+			customCss: options.customCss,
+			hideDownloadButton: options.hideDownloadButton,
+			hideSearch: options.hideSearch,
+			metaData: options.metaData,
+			cdn: options.cdn,
+			pageTitle: options.metaData?.title ?? "API Reference"
+		});
+	}
+};
+/**
+* Creates a plugin definition for the OpenAPI Fastify plugin.
+*
+* @param options - Plugin configuration options
+* @returns Plugin definition to pass to `app.usePlugin()`
+*
+* @example
+* ```typescript
+* import { NaviosFactory } from '@navios/core'
+* import { defineFastifyEnvironment } from '@navios/adapter-fastify'
+* import { defineOpenApiPlugin } from '@navios/openapi-fastify'
+*
+* const app = await NaviosFactory.create(AppModule, {
+*   adapter: defineFastifyEnvironment(),
+* })
+*
+* app.usePlugin(defineOpenApiPlugin({
+*   info: {
+*     title: 'My API',
+*     version: '1.0.0',
+*     description: 'API documentation',
+*   },
+*   servers: [
+*     { url: 'http://localhost:3000', description: 'Development' },
+*   ],
+*   securitySchemes: {
+*     bearerAuth: {
+*       type: 'http',
+*       scheme: 'bearer',
+*       bearerFormat: 'JWT',
+*     },
+*   },
+*   scalar: {
+*     theme: 'purple',
+*   },
+* }))
+*
+* await app.listen({ port: 3000 })
+* // API docs available at http://localhost:3000/docs
+* ```
+*/ function defineOpenApiPlugin(options) {
+	return {
+		plugin: new OpenApiFastifyPlugin(),
+		options
+	};
+}
+
+//#endregion
+export { ApiDeprecated, ApiExclude, ApiOperation, ApiSecurity, ApiStream, ApiSummary, ApiTag, OpenApiFastifyPlugin, applyGlobalPrefix, defineOpenApiPlugin, fastifyOpenApiPluginOptionsSchema, scalarMetaDataSchema, scalarOptionsSchema, scalarThemeSchema };
+//# sourceMappingURL=index.mjs.map

package/lib/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["z","scalarThemeSchema","enum","scalarMetaDataSchema","object","title","string","optional","description","ogDescription","ogTitle","ogImage","twitterCard","scalarOptionsSchema","theme","favicon","logo","hideDownloadButton","boolean","hideSearch","customCss","metaData","cdn","fastifyOpenApiPluginOptionsSchema","jsonPath","default","yamlPath","docsPath","scalar","disableScalar","disableYaml","applyGlobalPrefix","document","globalPrefix","options","servers","length","url","description","OpenApiGeneratorService","getHtmlDocument","stringify","yamlStringify","fastifyOpenApiPluginOptionsSchema","applyGlobalPrefix","OpenApiFastifyPlugin","name","register","context","options","fastify","server","parsedOptions","parse","generator","container","get","document","generate","modules","documentWithServers","globalPrefix","jsonPath","_request","reply","send","disableYaml","yamlPath","type","disableScalar","docsPath","scalarOptions","scalar","html","generateScalarHtml","specUrl","url","theme","favicon","customCss","hideDownloadButton","hideSearch","metaData","cdn","pageTitle","title","defineOpenApiPlugin","plugin"],"sources":["../src/schemas/openapi-fastify-options.schema.mts","../src/utils/apply-global-prefix.util.mts","../src/openapi-fastify.plugin.mts"],"sourcesContent":["import { z } from 'zod'\n\n/**\n * Zod schema for Scalar UI theme options\n */\nexport const scalarThemeSchema = z.enum([\n  'default',\n  'alternate',\n  'moon',\n  'purple',\n  'solarized',\n  'bluePlanet',\n  'saturn',\n  'kepler',\n  'mars',\n  'deepSpace',\n  'laserwave',\n  'elysiajs',\n  'fastify',\n  'none',\n])\n\n/**\n * Zod schema for Scalar UI metadata\n */\nexport const scalarMetaDataSchema = z\n  .object({\n    title: z.string().optional(),\n    description: z.string().optional(),\n    ogDescription: z.string().optional(),\n    ogTitle: z.string().optional(),\n    ogImage: z.string().optional(),\n    twitterCard: z.string().optional(),\n  })\n  .optional()\n\n/**\n * Zod schema for Scalar UI configuration options\n */\nexport const scalarOptionsSchema = z.object({\n  /**\n   * Theme for Scalar UI\n   * @default 'default'\n   */\n  theme: scalarThemeSchema.optional(),\n\n  /**\n   * Custom favicon URL\n   */\n  favicon: z.string().optional(),\n\n  /**\n   * Custom logo URL\n   */\n  logo: z.string().optional(),\n\n  /**\n   * Hide the \"Download OpenAPI Spec\" button\n   * @default false\n   */\n  hideDownloadButton: z.boolean().optional(),\n\n  /**\n   * Hide the \"Search\" input\n   * @default false\n   */\n  hideSearch: z.boolean().optional(),\n\n  /**\n   * Custom CSS to inject\n   */\n  customCss: z.string().optional(),\n\n  /**\n   * Meta data for the HTML page\n   */\n  metaData: scalarMetaDataSchema,\n\n  /**\n   * CDN URL for Scalar API Reference\n   * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'\n   */\n  cdn: z.string().optional(),\n})\n\n/**\n * Zod schema for Fastify OpenAPI plugin options\n */\nexport const fastifyOpenApiPluginOptionsSchema = z.object({\n  /**\n   * Path to serve OpenAPI JSON\n   * @default '/openapi.json'\n   */\n  jsonPath: z.string().optional().default('/openapi.json'),\n\n  /**\n   * Path to serve OpenAPI YAML\n   * @default '/openapi.yaml'\n   */\n  yamlPath: z.string().optional().default('/openapi.yaml'),\n\n  /**\n   * Path to serve Scalar UI\n   * @default '/docs'\n   */\n  docsPath: z.string().optional().default('/docs'),\n\n  /**\n   * Scalar UI configuration\n   */\n  scalar: scalarOptionsSchema.optional(),\n\n  /**\n   * Disable Scalar UI (only serve JSON/YAML)\n   * @default false\n   */\n  disableScalar: z.boolean().optional().default(false),\n\n  /**\n   * Disable YAML endpoint\n   * @default true\n   */\n  disableYaml: z.boolean().optional().default(true),\n})\n\nexport type ScalarTheme = z.infer<typeof scalarThemeSchema>\nexport type ScalarMetaData = z.infer<typeof scalarMetaDataSchema>\nexport type ScalarOptions = z.infer<typeof scalarOptionsSchema>\nexport type FastifyOpenApiPluginOptionsBase = z.infer<typeof fastifyOpenApiPluginOptionsSchema>\n","import type { OpenApiGeneratorOptions } from '@navios/openapi'\n\n/**\n * OpenAPI document shape (minimal interface for typing)\n */\nexport interface OpenAPIDocument {\n  openapi: string\n  info: {\n    title: string\n    version: string\n  }\n  paths?: Record<string, unknown>\n  servers?: Array<{\n    url: string\n    description?: string\n  }>\n}\n\n/**\n * Applies global prefix to OpenAPI servers if needed.\n *\n * @param document - The OpenAPI document to modify\n * @param globalPrefix - The global route prefix (e.g., '/api/v1')\n * @param options - Plugin options that may contain server configuration\n * @returns The document with servers array updated if applicable\n */\nexport function applyGlobalPrefix<T extends OpenAPIDocument>(\n  document: T,\n  globalPrefix: string,\n  options: OpenApiGeneratorOptions,\n): T {\n  // If servers are already defined, don't modify\n  if (options.servers && options.servers.length > 0) {\n    return document\n  }\n\n  // If no global prefix, return as-is\n  if (!globalPrefix) {\n    return document\n  }\n\n  // Add a default server with the global prefix\n  return {\n    ...document,\n    servers: [\n      {\n        url: globalPrefix,\n        description: 'API with global prefix',\n      },\n    ],\n  }\n}\n","import type {\n  NaviosPlugin,\n  PluginContext,\n  PluginDefinition,\n} from '@navios/core'\nimport type { OpenApiGeneratorOptions } from '@navios/openapi'\nimport type { FastifyInstance } from 'fastify'\n\nimport { OpenApiGeneratorService } from '@navios/openapi'\n\nimport { getHtmlDocument } from '@scalar/core/libs/html-rendering'\nimport { stringify as yamlStringify } from 'yaml'\n\nimport type {\n  FastifyOpenApiPluginOptionsBase,\n  ScalarOptions,\n  ScalarTheme,\n} from './schemas/index.mjs'\n\nimport { fastifyOpenApiPluginOptionsSchema } from './schemas/index.mjs'\nimport { applyGlobalPrefix } from './utils/index.mjs'\n\n/**\n * Combined options for the Fastify OpenAPI plugin.\n * Extends OpenApiGeneratorOptions with Fastify-specific settings.\n */\nexport interface FastifyOpenApiPluginOptions\n  extends OpenApiGeneratorOptions, Partial<FastifyOpenApiPluginOptionsBase> {}\n\n/**\n * Class-based OpenAPI Fastify plugin that integrates with Navios plugin system.\n *\n * This plugin:\n * - Scans all registered modules for endpoints\n * - Generates an OpenAPI 3.1 document\n * - Serves the document as JSON and optionally YAML\n * - Provides Scalar UI for interactive documentation\n */\nexport class OpenApiFastifyPlugin implements NaviosPlugin<FastifyOpenApiPluginOptions> {\n  readonly name = 'openapi-fastify'\n\n  async register(\n    context: PluginContext,\n    options: FastifyOpenApiPluginOptions,\n  ): Promise<void> {\n    const fastify = context.server as FastifyInstance\n\n    // Parse and validate options with defaults\n    const parsedOptions = fastifyOpenApiPluginOptionsSchema.parse(options)\n\n    // Get the generator service from the container\n    const generator = await context.container.get(OpenApiGeneratorService)\n\n    // Generate OpenAPI document from discovered endpoints\n    const document = generator.generate(context.modules, options)\n\n    // Apply global prefix to servers if not already set\n    const documentWithServers = applyGlobalPrefix(\n      document,\n      context.globalPrefix,\n      options,\n    )\n\n    // Register JSON endpoint\n    const jsonPath = parsedOptions.jsonPath\n    fastify.get(jsonPath, async (_request, reply) => {\n      return reply.send(documentWithServers)\n    })\n\n    // Register YAML endpoint (disabled by default)\n    if (!parsedOptions.disableYaml) {\n      const yamlPath = parsedOptions.yamlPath\n      fastify.get(yamlPath, async (_request, reply) => {\n        reply.type('text/yaml')\n        return reply.send(yamlStringify(documentWithServers))\n      })\n    }\n\n    // Register Scalar UI (unless disabled)\n    if (!parsedOptions.disableScalar) {\n      const docsPath = parsedOptions.docsPath\n      const scalarOptions = options.scalar ?? {}\n\n      // Generate HTML document using @scalar/core\n      const html = this.generateScalarHtml(jsonPath, scalarOptions)\n\n      fastify.get(docsPath, async (_request, reply) => {\n        reply.type('text/html')\n        return reply.send(html)\n      })\n    }\n  }\n\n  /**\n   * Generates the Scalar API Reference HTML document.\n   *\n   * @param specUrl - URL to the OpenAPI JSON specification\n   * @param options - Scalar UI configuration options\n   * @returns Complete HTML document string\n   */\n  private generateScalarHtml(specUrl: string, options: ScalarOptions): string {\n    return getHtmlDocument({\n      url: specUrl,\n      theme: options.theme ?? 'default',\n      favicon: options.favicon,\n      customCss: options.customCss,\n      hideDownloadButton: options.hideDownloadButton,\n      hideSearch: options.hideSearch,\n      metaData: options.metaData,\n      cdn: options.cdn,\n      pageTitle: options.metaData?.title ?? 'API Reference',\n    })\n  }\n}\n\n/**\n * Creates a plugin definition for the OpenAPI Fastify plugin.\n *\n * @param options - Plugin configuration options\n * @returns Plugin definition to pass to `app.usePlugin()`\n *\n * @example\n * ```typescript\n * import { NaviosFactory } from '@navios/core'\n * import { defineFastifyEnvironment } from '@navios/adapter-fastify'\n * import { defineOpenApiPlugin } from '@navios/openapi-fastify'\n *\n * const app = await NaviosFactory.create(AppModule, {\n *   adapter: defineFastifyEnvironment(),\n * })\n *\n * app.usePlugin(defineOpenApiPlugin({\n *   info: {\n *     title: 'My API',\n *     version: '1.0.0',\n *     description: 'API documentation',\n *   },\n *   servers: [\n *     { url: 'http://localhost:3000', description: 'Development' },\n *   ],\n *   securitySchemes: {\n *     bearerAuth: {\n *       type: 'http',\n *       scheme: 'bearer',\n *       bearerFormat: 'JWT',\n *     },\n *   },\n *   scalar: {\n *     theme: 'purple',\n *   },\n * }))\n *\n * await app.listen({ port: 3000 })\n * // API docs available at http://localhost:3000/docs\n * ```\n */\nexport function defineOpenApiPlugin(\n  options: FastifyOpenApiPluginOptions,\n): PluginDefinition<FastifyOpenApiPluginOptions> {\n  return {\n    plugin: new OpenApiFastifyPlugin(),\n    options,\n  }\n}\n\n// Re-export types for convenience\nexport type { ScalarOptions, ScalarTheme }\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@navios/openapi-fastify",
+  "version": "0.7.0",
+  "author": {
+    "name": "Oleksandr Hanzha",
+    "email": "alex@granted.name"
+  },
+  "repository": {
+    "directory": "packages/openapi-fastify",
+    "type": "git",
+    "url": "https://github.com/Arilas/navios.git"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@navios/adapter-fastify": "^0.7.1",
+    "@navios/core": "^0.7.1",
+    "@navios/openapi": "^0.7.0",
+    "fastify": "^5.0.0",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "typings": "./lib/index.d.mts",
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.mjs",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.mts",
+        "default": "./lib/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.cts",
+        "default": "./lib/index.cjs"
+      }
+    }
+  },
+  "devDependencies": {
+    "@navios/adapter-fastify": "^0.7.1",
+    "@navios/core": "^0.7.1",
+    "@navios/openapi": "^0.7.0",
+    "fastify": "^5.6.2",
+    "typescript": "^5.9.3",
+    "zod": "^4.2.1"
+  },
+  "dependencies": {
+    "@scalar/core": "^0.3.28",
+    "yaml": "^2.8.2"
+  }
+}

package/project.json

@@ -0,0 +1,66 @@
+{
+  "name": "@navios/openapi-fastify",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/openapi-fastify/src",
+  "prefix": "openapi-fastify",
+  "tags": [],
+  "projectType": "library",
+  "targets": {
+    "check": {
+      "executor": "nx:run-commands",
+      "outputs": ["{projectRoot}/dist"],
+      "inputs": [
+        "^projectSources",
+        "projectSources",
+        "{projectRoot}/tsconfig.json",
+        "{projectRoot}/tsconfig.lib.json"
+      ],
+      "options": {
+        "command": ["tsc -b"],
+        "cwd": "packages/openapi-fastify"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "inputs": ["^projectSources", "project"],
+      "options": {
+        "command": "oxlint --fix",
+        "cwd": "packages/openapi-fastify"
+      }
+    },
+    "test:ci": {
+      "executor": "nx:run-commands",
+      "inputs": ["^projectSources", "project"],
+      "options": {
+        "command": "vitest run",
+        "cwd": "packages/openapi-fastify"
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "inputs": ["projectSources", "{projectRoot}/tsdown.config.mts"],
+      "outputs": ["{projectRoot}/lib"],
+      "dependsOn": ["check", "lint"],
+      "options": {
+        "command": "tsdown",
+        "cwd": "packages/openapi-fastify"
+      }
+    },
+    "publish": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "yarn npm publish --access public",
+        "cwd": "packages/openapi-fastify"
+      }
+    },
+    "publish:next": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build"],
+      "options": {
+        "command": "yarn npm publish --access public --tag next",
+        "cwd": "packages/openapi-fastify"
+      }
+    }
+  }
+}

package/src/index.mts

@@ -0,0 +1,41 @@
+// Plugin
+export {
+  defineOpenApiPlugin,
+  OpenApiFastifyPlugin,
+  type FastifyOpenApiPluginOptions,
+  type ScalarOptions,
+  type ScalarTheme,
+} from './openapi-fastify.plugin.mjs'
+
+// Schemas
+export {
+  fastifyOpenApiPluginOptionsSchema,
+  scalarOptionsSchema,
+  scalarThemeSchema,
+  scalarMetaDataSchema,
+} from './schemas/index.mjs'
+
+// Utils
+export { applyGlobalPrefix } from './utils/index.mjs'
+
+// Re-export core OpenAPI types for convenience
+export type {
+  OpenApiGeneratorOptions,
+  OpenApiEndpointMetadata,
+  ApiOperationOptions,
+  ApiTagOptions,
+  ApiStreamOptions,
+  ApiDeprecatedOptions,
+  ApiSecurityRequirement,
+} from '@navios/openapi'
+
+// Re-export decorators for convenience
+export {
+  ApiTag,
+  ApiOperation,
+  ApiSummary,
+  ApiDeprecated,
+  ApiSecurity,
+  ApiExclude,
+  ApiStream,
+} from '@navios/openapi'