@navios/openapi 0.7.0

package/src/__tests__/services.spec.mts

@@ -0,0 +1,216 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { z } from 'zod/v4'
+
+import { TestContainer } from '@navios/di'
+
+import { SchemaConverterService } from '../services/schema-converter.service.mjs'
+import { PathBuilderService } from '../services/path-builder.service.mjs'
+
+describe('OpenAPI Services', () => {
+  let container: TestContainer
+
+  beforeEach(() => {
+    container = new TestContainer()
+  })
+
+  afterEach(async () => {
+    await container.dispose()
+  })
+
+  describe('SchemaConverterService', () => {
+    it('should convert string schema', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.string()
+      const result = service.convert(schema)
+
+      expect(result.schema).toEqual({ type: 'string' })
+    })
+
+    it('should convert number schema', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.number()
+      const result = service.convert(schema)
+
+      expect(result.schema).toEqual({ type: 'number' })
+    })
+
+    it('should convert boolean schema', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.boolean()
+      const result = service.convert(schema)
+
+      expect(result.schema).toEqual({ type: 'boolean' })
+    })
+
+    it('should convert object schema', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.object({
+        id: z.string(),
+        name: z.string(),
+        age: z.number().optional(),
+      })
+      const result = service.convert(schema)
+
+      expect(result.schema).toMatchObject({
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          name: { type: 'string' },
+          age: { type: 'number' },
+        },
+        required: ['id', 'name'],
+      })
+    })
+
+    it('should convert array schema', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.array(z.string())
+      const result = service.convert(schema)
+
+      expect(result.schema).toMatchObject({
+        type: 'array',
+        items: { type: 'string' },
+      })
+    })
+
+    it('should convert enum schema', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.enum(['admin', 'user', 'guest'])
+      const result = service.convert(schema)
+
+      expect(result.schema).toMatchObject({
+        type: 'string',
+        enum: ['admin', 'user', 'guest'],
+      })
+    })
+
+    it('should convert union schema', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.union([z.string(), z.number()])
+      const result = service.convert(schema)
+
+      expect(result.schema).toMatchObject({
+        anyOf: [{ type: 'string' }, { type: 'number' }],
+      })
+    })
+
+    it('should handle nullable schema', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.string().nullable()
+      const result = service.convert(schema)
+
+      // zod-openapi uses anyOf for nullable types in OpenAPI 3.1
+      expect(result.schema).toMatchObject({
+        anyOf: [{ type: 'string' }, { type: 'null' }],
+      })
+    })
+
+    it('should handle email format', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.string().email()
+      const result = service.convert(schema)
+
+      expect(result.schema).toMatchObject({
+        type: 'string',
+        format: 'email',
+      })
+    })
+
+    it('should handle uuid format', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.string().uuid()
+      const result = service.convert(schema)
+
+      expect(result.schema).toMatchObject({
+        type: 'string',
+        format: 'uuid',
+      })
+    })
+
+    it('should handle date schema', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.date()
+      const result = service.convert(schema)
+
+      // zod-openapi converts z.date() to just string type
+      expect(result.schema).toMatchObject({
+        type: 'string',
+      })
+    })
+
+    it('should handle nested objects', async () => {
+      const service = await container.get(SchemaConverterService)
+      const schema = z.object({
+        user: z.object({
+          id: z.string(),
+          profile: z.object({
+            bio: z.string().optional(),
+          }),
+        }),
+      })
+      const result = service.convert(schema)
+
+      expect(result.schema).toMatchObject({
+        type: 'object',
+        properties: {
+          user: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              profile: {
+                type: 'object',
+                properties: {
+                  bio: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+      })
+    })
+  })
+
+  describe('PathBuilderService', () => {
+    it('should convert $param to {param} format', async () => {
+      const service = await container.get(PathBuilderService)
+      expect(service.convertUrlParams('/users/$userId')).toBe('/users/{userId}')
+    })
+
+    it('should convert multiple params', async () => {
+      const service = await container.get(PathBuilderService)
+      expect(service.convertUrlParams('/users/$userId/posts/$postId')).toBe(
+        '/users/{userId}/posts/{postId}',
+      )
+    })
+
+    it('should handle URLs without params', async () => {
+      const service = await container.get(PathBuilderService)
+      expect(service.convertUrlParams('/users')).toBe('/users')
+    })
+
+    it('should handle params at the end', async () => {
+      const service = await container.get(PathBuilderService)
+      expect(service.convertUrlParams('/files/$fileId/download')).toBe(
+        '/files/{fileId}/download',
+      )
+    })
+
+    it('should extract single param', async () => {
+      const service = await container.get(PathBuilderService)
+      expect(service.extractUrlParamNames('/users/$userId')).toEqual(['userId'])
+    })
+
+    it('should extract multiple params', async () => {
+      const service = await container.get(PathBuilderService)
+      expect(service.extractUrlParamNames('/users/$userId/posts/$postId')).toEqual([
+        'userId',
+        'postId',
+      ])
+    })
+
+    it('should return empty array for no params', async () => {
+      const service = await container.get(PathBuilderService)
+      expect(service.extractUrlParamNames('/users')).toEqual([])
+    })
+  })
+})

package/src/decorators/api-deprecated.decorator.mts

@@ -0,0 +1,45 @@
+import { AttributeFactory } from '@navios/core'
+import { z } from 'zod/v4'
+
+import { ApiDeprecatedToken } from '../tokens/index.mjs'
+
+const ApiDeprecatedSchema = z.object({
+  message: z.string().optional(),
+})
+
+/** Options for the @ApiDeprecated decorator, inferred from the schema */
+export type ApiDeprecatedOptions = z.infer<typeof ApiDeprecatedSchema>
+
+const BaseApiDeprecated = AttributeFactory.createAttribute(
+  ApiDeprecatedToken,
+  ApiDeprecatedSchema,
+)
+
+/**
+ * Marks an endpoint as deprecated.
+ *
+ * Deprecated endpoints are shown with a visual indicator in documentation
+ * and may include a migration message.
+ *
+ * @param message - Optional deprecation message
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   // Simple deprecation
+ *   @Endpoint(legacyGetUser)
+ *   @ApiDeprecated()
+ *   async getLegacyUser() {}
+ *
+ *   // With migration message
+ *   @Endpoint(oldCreateUser)
+ *   @ApiDeprecated('Use POST /v2/users instead')
+ *   async oldCreateUser() {}
+ * }
+ * ```
+ */
+export function ApiDeprecated(message?: string) {
+  return BaseApiDeprecated({ message })
+}
+

package/src/decorators/api-exclude.decorator.mts

@@ -0,0 +1,29 @@
+import { AttributeFactory } from '@navios/core'
+
+import { ApiExcludeToken } from '../tokens/index.mjs'
+
+/**
+ * Excludes an endpoint from OpenAPI documentation.
+ *
+ * Use this decorator for internal endpoints that should not be visible
+ * in the public API documentation.
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class HealthController {
+ *   @Endpoint(healthCheck)
+ *   @ApiExclude()
+ *   async healthCheck() {
+ *     return { status: 'ok' }
+ *   }
+ *
+ *   @Endpoint(internalMetrics)
+ *   @ApiExclude()
+ *   async internalMetrics() {
+ *     return { ... }
+ *   }
+ * }
+ * ```
+ */
+export const ApiExclude = AttributeFactory.createAttribute(ApiExcludeToken)

package/src/decorators/api-operation.decorator.mts

@@ -0,0 +1,59 @@
+import { AttributeFactory } from '@navios/core'
+import { z } from 'zod/v4'
+
+import { ApiOperationToken } from '../tokens/index.mjs'
+
+const ApiOperationSchema = z.object({
+  summary: z.string().optional(),
+  description: z.string().optional(),
+  operationId: z.string().optional(),
+  deprecated: z.boolean().optional(),
+  externalDocs: z
+    .object({
+      url: z.string(),
+      description: z.string().optional(),
+    })
+    .optional(),
+})
+
+/** Options for the @ApiOperation decorator, inferred from the schema */
+export type ApiOperationOptions = z.infer<typeof ApiOperationSchema>
+
+/**
+ * Provides detailed operation metadata for an endpoint.
+ *
+ * Use this decorator when you need to specify multiple operation properties.
+ * For simple cases, consider using @ApiSummary instead.
+ *
+ * @param options - Operation configuration options
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUser)
+ *   @ApiOperation({
+ *     summary: 'Get user by ID',
+ *     description: 'Retrieves a user by their unique identifier. Returns 404 if not found.',
+ *     operationId: 'getUserById',
+ *   })
+ *   async getUser(params: EndpointParams<typeof getUser>) {}
+ *
+ *   @Endpoint(legacyGetUser)
+ *   @ApiOperation({
+ *     summary: 'Get user (legacy)',
+ *     deprecated: true,
+ *     externalDocs: {
+ *       url: 'https://docs.example.com/migration',
+ *       description: 'Migration guide'
+ *     }
+ *   })
+ *   async getLegacyUser() {}
+ * }
+ * ```
+ */
+export const ApiOperation = AttributeFactory.createAttribute(
+  ApiOperationToken,
+  ApiOperationSchema,
+)
+

package/src/decorators/api-security.decorator.mts

@@ -0,0 +1,44 @@
+import { AttributeFactory } from '@navios/core'
+import { z } from 'zod/v4'
+
+import { ApiSecurityToken } from '../tokens/index.mjs'
+
+const ApiSecuritySchema = z.record(z.string(), z.array(z.string()))
+
+/** Security requirement for an endpoint, inferred from the schema */
+export type ApiSecurityRequirement = z.infer<typeof ApiSecuritySchema>
+
+/**
+ * Specifies security requirements for an endpoint.
+ *
+ * The security requirement object maps security scheme names to their scopes.
+ * For schemes that don't use scopes (like API keys), use an empty array.
+ *
+ * @param requirements - Security requirements object
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   // Require bearer token authentication
+ *   @Endpoint(getUser)
+ *   @ApiSecurity({ bearerAuth: [] })
+ *   async getUser() {}
+ *
+ *   // Require multiple authentication methods
+ *   @Endpoint(adminEndpoint)
+ *   @ApiSecurity({ bearerAuth: [], apiKey: [] })
+ *   async adminAction() {}
+ *
+ *   // OAuth2 with specific scopes
+ *   @Endpoint(writeUser)
+ *   @ApiSecurity({ oauth2: ['users:write', 'users:read'] })
+ *   async writeUser() {}
+ * }
+ * ```
+ */
+export const ApiSecurity = AttributeFactory.createAttribute(
+  ApiSecurityToken,
+  ApiSecuritySchema,
+)
+

package/src/decorators/api-stream.decorator.mts

@@ -0,0 +1,55 @@
+import { AttributeFactory } from '@navios/core'
+import { z } from 'zod/v4'
+
+import { ApiStreamToken } from '../tokens/index.mjs'
+
+const ApiStreamSchema = z.object({
+  contentType: z.string(),
+  description: z.string().optional(),
+})
+
+/** Options for the @ApiStream decorator, inferred from the schema */
+export type ApiStreamOptions = z.infer<typeof ApiStreamSchema>
+
+/**
+ * Specifies content type and description for stream endpoints.
+ *
+ * Stream endpoints don't have a responseSchema, so this decorator provides
+ * the necessary metadata for OpenAPI documentation.
+ *
+ * @param options - Stream response options
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class FileController {
+ *   // Binary file download
+ *   @Stream(downloadFile)
+ *   @ApiStream({
+ *     contentType: 'application/octet-stream',
+ *     description: 'Download file as binary stream'
+ *   })
+ *   async download(params: StreamParams<typeof downloadFile>, reply: Reply) {
+ *     // Stream implementation
+ *   }
+ * }
+ *
+ * @Controller()
+ * export class EventController {
+ *   // Server-Sent Events
+ *   @Stream(streamEvents)
+ *   @ApiStream({
+ *     contentType: 'text/event-stream',
+ *     description: 'Real-time event stream'
+ *   })
+ *   async stream(params: StreamParams<typeof streamEvents>, reply: Reply) {
+ *     // SSE implementation
+ *   }
+ * }
+ * ```
+ */
+export const ApiStream = AttributeFactory.createAttribute(
+  ApiStreamToken,
+  ApiStreamSchema,
+)
+

package/src/decorators/api-summary.decorator.mts

@@ -0,0 +1,33 @@
+import { AttributeFactory } from '@navios/core'
+import { z } from 'zod/v4'
+
+import { ApiSummaryToken } from '../tokens/index.mjs'
+
+const ApiSummarySchema = z.string()
+
+/**
+ * Shorthand decorator for adding just a summary to an endpoint.
+ *
+ * This is equivalent to `@ApiOperation({ summary: '...' })` but more concise.
+ *
+ * @param summary - Short summary text for the endpoint
+ *
+ * @example
+ * ```typescript
+ * @Controller()
+ * export class UserController {
+ *   @Endpoint(getUser)
+ *   @ApiSummary('Get user by ID')
+ *   async getUser() {}
+ *
+ *   @Endpoint(createUser)
+ *   @ApiSummary('Create a new user')
+ *   async createUser() {}
+ * }
+ * ```
+ */
+export const ApiSummary = AttributeFactory.createAttribute(
+  ApiSummaryToken,
+  ApiSummarySchema,
+)
+

package/src/decorators/api-tag.decorator.mts

@@ -0,0 +1,51 @@
+import { AttributeFactory } from '@navios/core'
+import { z } from 'zod/v4'
+
+import { ApiTagToken } from '../tokens/index.mjs'
+
+const ApiTagSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+})
+
+/** Options for the @ApiTag decorator, inferred from the schema */
+export type ApiTagOptions = z.infer<typeof ApiTagSchema>
+
+const BaseApiTag = AttributeFactory.createAttribute(ApiTagToken, ApiTagSchema)
+
+/**
+ * Groups endpoints under a specific tag/folder in the documentation.
+ *
+ * Can be applied to controllers (affects all endpoints) or individual methods.
+ * When applied to both, the method-level tag takes precedence.
+ *
+ * @param name - The tag name
+ * @param description - Optional tag description
+ *
+ * @example
+ * ```typescript
+ * // Apply to entire controller
+ * @Controller()
+ * @ApiTag('Users', 'User management operations')
+ * export class UserController {
+ *   @Endpoint(getUser)
+ *   async getUser() {}
+ * }
+ *
+ * // Apply to individual endpoint
+ * @Controller()
+ * export class MixedController {
+ *   @Endpoint(getUser)
+ *   @ApiTag('Users')
+ *   async getUser() {}
+ *
+ *   @Endpoint(getOrder)
+ *   @ApiTag('Orders')
+ *   async getOrder() {}
+ * }
+ * ```
+ */
+export function ApiTag(name: string, description?: string) {
+  return BaseApiTag({ name, description })
+}
+

package/src/decorators/index.mts

@@ -0,0 +1,7 @@
+export { ApiTag, type ApiTagOptions } from './api-tag.decorator.mjs'
+export { ApiOperation, type ApiOperationOptions } from './api-operation.decorator.mjs'
+export { ApiSummary } from './api-summary.decorator.mjs'
+export { ApiDeprecated, type ApiDeprecatedOptions } from './api-deprecated.decorator.mjs'
+export { ApiSecurity, type ApiSecurityRequirement } from './api-security.decorator.mjs'
+export { ApiExclude } from './api-exclude.decorator.mjs'
+export { ApiStream, type ApiStreamOptions } from './api-stream.decorator.mjs'

package/src/index.mts

@@ -0,0 +1,42 @@
+// Decorators and their types
+export {
+  ApiTag,
+  ApiOperation,
+  ApiSummary,
+  ApiDeprecated,
+  ApiSecurity,
+  ApiExclude,
+  ApiStream,
+  type ApiOperationOptions,
+  type ApiTagOptions,
+  type ApiStreamOptions,
+  type ApiDeprecatedOptions,
+  type ApiSecurityRequirement,
+} from './decorators/index.mjs'
+
+// Metadata types
+export type { OpenApiEndpointMetadata } from './metadata/index.mjs'
+
+// Services (Injectable classes - recommended for DI integration)
+export {
+  OpenApiGeneratorService,
+  type OpenApiGeneratorOptions,
+  EndpointScannerService,
+  type DiscoveredEndpoint,
+  MetadataExtractorService,
+  SchemaConverterService,
+  type SchemaConversionResult,
+  PathBuilderService,
+  type PathItemResult,
+} from './services/index.mjs'
+
+// Tokens (for advanced usage)
+export {
+  ApiTagToken,
+  ApiOperationToken,
+  ApiSummaryToken,
+  ApiDeprecatedToken,
+  ApiSecurityToken,
+  ApiExcludeToken,
+  ApiStreamToken,
+} from './tokens/index.mjs'

package/src/metadata/index.mts

@@ -0,0 +1,2 @@
+// Re-export metadata types
+export type { OpenApiEndpointMetadata } from './openapi.metadata.mjs'

package/src/metadata/openapi.metadata.mts

@@ -0,0 +1,30 @@
+import type { ApiSecurityRequirement, ApiStreamOptions } from '../decorators/index.mjs'
+
+/**
+ * Extracted OpenAPI metadata for an endpoint
+ */
+export interface OpenApiEndpointMetadata {
+  /** Tags for grouping endpoints */
+  tags: string[]
+  /** Short summary */
+  summary?: string
+  /** Detailed description */
+  description?: string
+  /** Unique operation identifier */
+  operationId?: string
+  /** Whether the endpoint is deprecated */
+  deprecated: boolean
+  /** Deprecation message */
+  deprecationMessage?: string
+  /** Security requirements */
+  security?: ApiSecurityRequirement[]
+  /** External documentation link */
+  externalDocs?: {
+    url: string
+    description?: string
+  }
+  /** Stream content type (for stream endpoints) */
+  stream?: ApiStreamOptions
+  /** Whether to exclude from documentation */
+  excluded: boolean
+}