@navios/openapi-fastify 0.7.0

package/src/openapi-fastify.plugin.mts

@@ -0,0 +1,167 @@
+import type {
+  NaviosPlugin,
+  PluginContext,
+  PluginDefinition,
+} from '@navios/core'
+import type { OpenApiGeneratorOptions } from '@navios/openapi'
+import type { FastifyInstance } from 'fastify'
+
+import { OpenApiGeneratorService } from '@navios/openapi'
+
+import { getHtmlDocument } from '@scalar/core/libs/html-rendering'
+import { stringify as yamlStringify } from 'yaml'
+
+import type {
+  FastifyOpenApiPluginOptionsBase,
+  ScalarOptions,
+  ScalarTheme,
+} from './schemas/index.mjs'
+
+import { fastifyOpenApiPluginOptionsSchema } from './schemas/index.mjs'
+import { applyGlobalPrefix } from './utils/index.mjs'
+
+/**
+ * Combined options for the Fastify OpenAPI plugin.
+ * Extends OpenApiGeneratorOptions with Fastify-specific settings.
+ */
+export interface FastifyOpenApiPluginOptions
+  extends OpenApiGeneratorOptions, 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
+ */
+export class OpenApiFastifyPlugin implements NaviosPlugin<FastifyOpenApiPluginOptions> {
+  readonly name = 'openapi-fastify'
+
+  async register(
+    context: PluginContext,
+    options: FastifyOpenApiPluginOptions,
+  ): Promise<void> {
+    const fastify = context.server as FastifyInstance
+
+    // Parse and validate options with defaults
+    const parsedOptions = fastifyOpenApiPluginOptionsSchema.parse(options)
+
+    // Get the generator service from the container
+    const generator = await context.container.get(OpenApiGeneratorService)
+
+    // Generate OpenAPI document from discovered endpoints
+    const document = generator.generate(context.modules, options)
+
+    // Apply global prefix to servers if not already set
+    const documentWithServers = applyGlobalPrefix(
+      document,
+      context.globalPrefix,
+      options,
+    )
+
+    // Register JSON endpoint
+    const jsonPath = parsedOptions.jsonPath
+    fastify.get(jsonPath, async (_request, reply) => {
+      return reply.send(documentWithServers)
+    })
+
+    // Register YAML endpoint (disabled by default)
+    if (!parsedOptions.disableYaml) {
+      const yamlPath = parsedOptions.yamlPath
+      fastify.get(yamlPath, async (_request, reply) => {
+        reply.type('text/yaml')
+        return reply.send(yamlStringify(documentWithServers))
+      })
+    }
+
+    // Register Scalar UI (unless disabled)
+    if (!parsedOptions.disableScalar) {
+      const docsPath = parsedOptions.docsPath
+      const scalarOptions = options.scalar ?? {}
+
+      // Generate HTML document using @scalar/core
+      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
+   */
+  private generateScalarHtml(specUrl: string, options: ScalarOptions): string {
+    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
+ * ```
+ */
+export function defineOpenApiPlugin(
+  options: FastifyOpenApiPluginOptions,
+): PluginDefinition<FastifyOpenApiPluginOptions> {
+  return {
+    plugin: new OpenApiFastifyPlugin(),
+    options,
+  }
+}
+
+// Re-export types for convenience
+export type { ScalarOptions, ScalarTheme }

package/src/schemas/index.mts

@@ -0,0 +1,10 @@
+export {
+  fastifyOpenApiPluginOptionsSchema,
+  scalarMetaDataSchema,
+  scalarOptionsSchema,
+  scalarThemeSchema,
+  type FastifyOpenApiPluginOptionsBase,
+  type ScalarMetaData,
+  type ScalarOptions,
+  type ScalarTheme,
+} from './openapi-fastify-options.schema.mjs'

package/src/schemas/openapi-fastify-options.schema.mts

@@ -0,0 +1,129 @@
+import { z } from 'zod'
+
+/**
+ * Zod schema for Scalar UI theme options
+ */
+export const scalarThemeSchema = z.enum([
+  'default',
+  'alternate',
+  'moon',
+  'purple',
+  'solarized',
+  'bluePlanet',
+  'saturn',
+  'kepler',
+  'mars',
+  'deepSpace',
+  'laserwave',
+  'elysiajs',
+  'fastify',
+  'none',
+])
+
+/**
+ * Zod schema for Scalar UI metadata
+ */
+export 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
+ */
+export const scalarOptionsSchema = z.object({
+  /**
+   * Theme for Scalar UI
+   * @default 'default'
+   */
+  theme: scalarThemeSchema.optional(),
+
+  /**
+   * Custom favicon URL
+   */
+  favicon: z.string().optional(),
+
+  /**
+   * Custom logo URL
+   */
+  logo: z.string().optional(),
+
+  /**
+   * Hide the "Download OpenAPI Spec" button
+   * @default false
+   */
+  hideDownloadButton: z.boolean().optional(),
+
+  /**
+   * Hide the "Search" input
+   * @default false
+   */
+  hideSearch: z.boolean().optional(),
+
+  /**
+   * Custom CSS to inject
+   */
+  customCss: z.string().optional(),
+
+  /**
+   * Meta data for the HTML page
+   */
+  metaData: scalarMetaDataSchema,
+
+  /**
+   * CDN URL for Scalar API Reference
+   * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'
+   */
+  cdn: z.string().optional(),
+})
+
+/**
+ * Zod schema for Fastify OpenAPI plugin options
+ */
+export const fastifyOpenApiPluginOptionsSchema = z.object({
+  /**
+   * Path to serve OpenAPI JSON
+   * @default '/openapi.json'
+   */
+  jsonPath: z.string().optional().default('/openapi.json'),
+
+  /**
+   * Path to serve OpenAPI YAML
+   * @default '/openapi.yaml'
+   */
+  yamlPath: z.string().optional().default('/openapi.yaml'),
+
+  /**
+   * Path to serve Scalar UI
+   * @default '/docs'
+   */
+  docsPath: z.string().optional().default('/docs'),
+
+  /**
+   * Scalar UI configuration
+   */
+  scalar: scalarOptionsSchema.optional(),
+
+  /**
+   * Disable Scalar UI (only serve JSON/YAML)
+   * @default false
+   */
+  disableScalar: z.boolean().optional().default(false),
+
+  /**
+   * Disable YAML endpoint
+   * @default true
+   */
+  disableYaml: z.boolean().optional().default(true),
+})
+
+export type ScalarTheme = z.infer<typeof scalarThemeSchema>
+export type ScalarMetaData = z.infer<typeof scalarMetaDataSchema>
+export type ScalarOptions = z.infer<typeof scalarOptionsSchema>
+export type FastifyOpenApiPluginOptionsBase = z.infer<typeof fastifyOpenApiPluginOptionsSchema>

package/src/utils/apply-global-prefix.util.mts

@@ -0,0 +1,52 @@
+import type { OpenApiGeneratorOptions } from '@navios/openapi'
+
+/**
+ * OpenAPI document shape (minimal interface for typing)
+ */
+export 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
+ */
+export function applyGlobalPrefix<T extends OpenAPIDocument>(
+  document: T,
+  globalPrefix: string,
+  options: OpenApiGeneratorOptions,
+): T {
+  // If servers are already defined, don't modify
+  if (options.servers && options.servers.length > 0) {
+    return document
+  }
+
+  // If no global prefix, return as-is
+  if (!globalPrefix) {
+    return document
+  }
+
+  // Add a default server with the global prefix
+  return {
+    ...document,
+    servers: [
+      {
+        url: globalPrefix,
+        description: 'API with global prefix',
+      },
+    ],
+  }
+}

package/src/utils/index.mts

@@ -0,0 +1 @@
+export { applyGlobalPrefix, type OpenAPIDocument } from './apply-global-prefix.util.mjs'

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "Node18",
+    "outDir": "dist"
+  },
+  "references": [
+    { "path": "./tsconfig.lib.json" },
+    { "path": "../core" },
+    { "path": "../di" },
+    { "path": "../openapi" },
+    { "path": "../adapter-fastify" }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.spec.mts", "src/**/*.spec-d.mts"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*.mts"]
+}

package/tsdown.config.mts

@@ -0,0 +1,35 @@
+import { withFilter } from 'rolldown/filter'
+import { defineConfig } from 'tsdown'
+import swc from 'unplugin-swc'
+
+export default defineConfig({
+  entry: ['src/index.mts'],
+  outDir: 'lib',
+  format: ['esm', 'cjs'],
+  clean: true,
+  tsconfig: 'tsconfig.lib.json',
+  treeshake: true,
+  sourcemap: true,
+  platform: 'node',
+  external: ['@navios/core', '@navios/openapi', '@navios/adapter-fastify', 'fastify'],
+  dts: true,
+  target: 'es2022',
+  plugins: [
+    withFilter(
+      swc.rolldown({
+        jsc: {
+          target: 'es2022',
+          parser: {
+            syntax: 'typescript',
+            decorators: true,
+          },
+          transform: {
+            decoratorVersion: '2022-03',
+          },
+        },
+      }),
+      // Only run this transform if the file contains a decorator.
+      { transform: { code: '@' } },
+    ),
+  ],
+})

package/vitest.config.mts

@@ -0,0 +1,11 @@
+import { defineProject } from 'vitest/config'
+
+export default defineProject({
+  test: {
+    typecheck: {
+      enabled: true,
+      tsconfig: './tsconfig.lib.json',
+    },
+    include: ['src/**/*.spec.mts', 'src/**/*.spec-d.mts'],
+  },
+})