@furystack/rest-service 10.0.23 → 10.0.25

package/src/swagger/generate-swagger-json.ts

@@ -0,0 +1,123 @@
+import type { ApiEndpointDefinition, Operation, ParameterObject, SwaggerDocument } from '@furystack/rest'
+
+/**
+ * Converts a FuryStack API schema to an OpenAPI 3.1 compatible document
+ *
+ * @param schema - The FuryStack API schema to convert
+ * @returns A SwaggerDocument in OpenAPI 3.1 format
+ */
+export const generateSwaggerJsonFromApiSchema = ({
+  api,
+  title = 'FuryStack API',
+  description = 'API documentation generated from FuryStack API schema',
+  version = '1.0.0',
+}: {
+  api: Record<string, ApiEndpointDefinition>
+  title?: string
+  description?: string
+  version?: string
+}): SwaggerDocument => {
+  const swaggerJson: SwaggerDocument = {
+    openapi: '3.1.0',
+    info: {
+      title,
+      version,
+      description,
+    },
+    jsonSchemaDialect: 'https://spec.openapis.org/oas/3.1/dialect/base',
+    servers: [{ url: '/' }],
+    tags: [],
+    paths: {},
+    components: {
+      schemas: {},
+      securitySchemes: {
+        cookieAuth: {
+          type: 'apiKey',
+          in: 'cookie',
+          name: 'session',
+        },
+      },
+    },
+  }
+
+  for (const [path, definition] of Object.entries(api)) {
+    // Normalize path to OpenAPI format (convert :param to {param})
+    const normalizedPath = path.replace(/:([^/]+)/g, '{$1}')
+    if (!swaggerJson.paths![normalizedPath]) {
+      swaggerJson.paths![normalizedPath] = {}
+    }
+
+    // Extract path parameters
+    const pathParams = Array.from(path.matchAll(/:([^/]+)/g), (m) => m[1])
+    const parameters: ParameterObject[] = pathParams.map((param) => ({
+      name: param,
+      in: 'path',
+      required: true,
+      description: `Path parameter: ${param}`,
+      schema: { type: 'string' },
+    }))
+
+    // Build operation
+    const method = definition.method.toLowerCase()
+    const operation: Operation = {
+      summary: `${definition.method} ${path}`,
+      description: `Endpoint for ${path}`,
+      operationId: `${method}${path.replace(/\//g, '_').replace(/:/g, '').replace(/-/g, '_')}`,
+      security: definition.isAuthenticated ? [{ cookieAuth: [] }] : [],
+      parameters,
+      responses: {
+        '200': {
+          description: 'Successful operation',
+          content: {
+            'application/json': {
+              schema: definition.schemaName
+                ? { $ref: `#/components/schemas/${definition.schemaName}` }
+                : { type: 'object' },
+            },
+          },
+        },
+        '401': { description: 'Unauthorized' },
+        '500': { description: 'Internal server error' },
+      },
+    }
+
+    // Add schema to components if not already there
+    if (definition.schema && definition.schemaName) {
+      swaggerJson.components!.schemas![definition.schemaName] = definition.schema
+    }
+
+    // Assign the operation to the correct HTTP method property of PathItem
+    const pathItem = swaggerJson.paths![normalizedPath]
+    switch (method) {
+      case 'get':
+        pathItem.get = operation
+        break
+      case 'put':
+        pathItem.put = operation
+        break
+      case 'post':
+        pathItem.post = operation
+        break
+      case 'delete':
+        pathItem.delete = operation
+        break
+      case 'options':
+        pathItem.options = operation
+        break
+      case 'head':
+        pathItem.head = operation
+        break
+      case 'patch':
+        pathItem.patch = operation
+        break
+      case 'trace':
+        pathItem.trace = operation
+        break
+      default:
+        // Ignore unknown methods
+        break
+    }
+  }
+
+  return swaggerJson
+}

package/src/validate.integration.spec.schema.json

@@ -6,7 +6,6 @@
       "description": "Endpoint model for deleting entities",
       "properties": {
         "result": {
-          "additionalProperties": false,
           "type": "object"
         },
         "url": {
@@ -304,7 +303,6 @@
           "type": "object"
         },
         "result": {
-          "additionalProperties": false,
           "type": "object"
         },
         "url": {

package/src/validate.integration.spec.ts

@@ -1,6 +1,7 @@
 import { getStoreManager, InMemoryStore, User } from '@furystack/core'
 import { getPort } from '@furystack/core/port-generator'
 import { Injector } from '@furystack/inject'
+import type { SwaggerDocument, WithSchemaAction } from '@furystack/rest'
 import { createClient, ResponseError } from '@furystack/rest-client-fetch'
 import { usingAsync } from '@furystack/utils'
 import type Ajv from 'ajv'
@@ -14,15 +15,23 @@ import { Validate } from './validate.js'
 
 // To recreate: yarn ts-json-schema-generator -f tsconfig.json --no-type-check -p packages/rest-service/src/validate.integration.schema.ts -o packages/rest-service/src/validate.integration.spec.schema.json
 
-const createValidateApi = async () => {
+const name = crypto.randomUUID()
+const description = crypto.randomUUID()
+const version = crypto.randomUUID()
+
+const createValidateApi = async (options = { enableGetSchema: false }) => {
   const injector = new Injector()
   const port = getPort()
 
   getStoreManager(injector).addStore(new InMemoryStore({ model: User, primaryKey: 'username' }))
   getStoreManager(injector).addStore(new InMemoryStore({ model: DefaultSession, primaryKey: 'sessionId' }))
 
-  await useRestService<ValidationApi>({
+  const api = await useRestService<ValidationApi>({
     injector,
+    enableGetSchema: options.enableGetSchema,
+    name,
+    description,
+    version,
     api: {
       GET: {
         '/validate-query': Validate({
@@ -66,11 +75,173 @@ const createValidateApi = async () => {
 
   return {
     [Symbol.asyncDispose]: injector[Symbol.asyncDispose].bind(injector),
+    injector,
+    api,
     client,
   }
 }
 
 describe('Validation integration tests', () => {
+  describe('swagger.json schema definition', () => {
+    it('Should include name, description and version in the generated swagger.json', async () => {
+      await usingAsync(await createValidateApi({ enableGetSchema: true }), async ({ client }) => {
+        const result = await (client as ReturnType<typeof createClient<any>>)({
+          method: 'GET',
+          action: '/swagger.json',
+        })
+
+        expect(result.response.status).toBe(200)
+        expect(result.result).toBeDefined()
+
+        // Verify swagger document structure
+        const swaggerJson = result.result as SwaggerDocument
+        expect(swaggerJson.openapi).toBe('3.1.0')
+        expect(swaggerJson.info).toBeDefined()
+        expect(swaggerJson.info?.title).toBe(name)
+        expect(swaggerJson.info?.description).toBe(description)
+        expect(swaggerJson.info?.version).toBe(version)
+      })
+    })
+
+    it('Should return a 404 when not enabled', async () => {
+      await usingAsync(await createValidateApi({ enableGetSchema: false }), async ({ client }) => {
+        try {
+          await (client as ReturnType<typeof createClient<any>>)({
+            method: 'GET',
+            action: '/swagger.json',
+          })
+          expect.fail('Expected response error but got success')
+        } catch (error) {
+          expect(error).toBeInstanceOf(ResponseError)
+          expect((error as ResponseError).response.status).toBe(404)
+        }
+      })
+    })
+
+    it('Should return a generated swagger.json when enabled', async () => {
+      await usingAsync(await createValidateApi({ enableGetSchema: true }), async ({ client }) => {
+        const result = await (client as ReturnType<typeof createClient<any>>)({
+          method: 'GET',
+          action: '/swagger.json',
+        })
+
+        expect(result.response.status).toBe(200)
+        expect(result.result).toBeDefined()
+
+        // Verify swagger document structure
+        const swaggerJson = result.result as SwaggerDocument
+        expect(swaggerJson.openapi).toBe('3.1.0')
+        expect(swaggerJson.info).toBeDefined()
+        expect(swaggerJson.info?.title).toBe(name)
+        expect(swaggerJson.info?.description).toBe(description)
+        expect(swaggerJson.info?.version).toBe(version)
+        expect(swaggerJson.paths).toBeDefined()
+
+        // Verify our API endpoints are included
+        expect(swaggerJson.paths?.['/validate-query']).toBeDefined()
+        expect(swaggerJson.paths?.['/validate-url/{id}']).toBeDefined()
+        expect(swaggerJson.paths?.['/validate-headers']).toBeDefined()
+        expect(swaggerJson.paths?.['/validate-body']).toBeDefined()
+
+        // Verify components section
+        expect(swaggerJson.components).toBeDefined()
+        expect(swaggerJson.components?.schemas).toBeDefined()
+        expect(swaggerJson.components?.schemas?.ValidateQuery).toBeDefined()
+        expect(swaggerJson.components?.schemas?.ValidateUrl).toBeDefined()
+        expect(swaggerJson.components?.schemas?.ValidateHeaders).toBeDefined()
+        expect(swaggerJson.components?.schemas?.ValidateBody).toBeDefined()
+      })
+    })
+  })
+
+  describe('Validation metadata', () => {
+    it('Should return 404 when not enabled', async () => {
+      await usingAsync(await createValidateApi({ enableGetSchema: false }), async ({ client }) => {
+        try {
+          await (client as ReturnType<typeof createClient<WithSchemaAction<ValidationApi>>>)({
+            method: 'GET',
+            action: '/schema',
+            headers: {
+              accept: 'application/schema+json',
+            },
+          })
+        } catch (error) {
+          expect(error).toBeInstanceOf(ResponseError)
+          expect((error as ResponseError).response.status).toBe(404)
+        }
+      })
+    })
+
+    it('Should return a 406 when the accept header is not supported', async () => {
+      expect.assertions(2)
+      await usingAsync(await createValidateApi({ enableGetSchema: true }), async ({ client }) => {
+        try {
+          await (client as ReturnType<typeof createClient<WithSchemaAction<ValidationApi>>>)({
+            method: 'GET',
+            action: '/schema',
+            headers: {
+              accept: 'text/plain' as any,
+            },
+          })
+        } catch (error) {
+          expect(error).toBeInstanceOf(ResponseError)
+          expect((error as ResponseError).response.status).toBe(406)
+        }
+      })
+    })
+
+    it('Should return the validation metadata', async () => {
+      await usingAsync(await createValidateApi({ enableGetSchema: true }), async ({ client }) => {
+        const result = await (client as ReturnType<typeof createClient<WithSchemaAction<ValidationApi>>>)({
+          method: 'GET',
+          action: '/schema',
+          headers: {
+            accept: 'application/schema+json',
+          },
+        })
+
+        expect(result.response.status).toBe(200)
+        expect(result.result).toBeDefined()
+
+        expect(result.result.name).toBe(name)
+        expect(result.result.description).toBe(description)
+        expect(result.result.version).toBe(version)
+
+        expect(result.result.endpoints['/validate-query']).toBeDefined()
+
+        expect(result.result.endpoints['/validate-query'].schema).toStrictEqual(schema)
+        expect(result.result.endpoints['/validate-query'].schemaName).toBe('ValidateQuery')
+        expect(result.result.endpoints['/validate-query'].method).toBe('GET')
+        expect(result.result.endpoints['/validate-query'].path).toBe('/validate-query')
+        expect(result.result.endpoints['/validate-query'].isAuthenticated).toBe(false)
+
+        expect(result.result.endpoints['/validate-url/:id']).toBeDefined()
+        expect(result.result.endpoints['/validate-url/:id'].schema).toStrictEqual(schema)
+        expect(result.result.endpoints['/validate-url/:id'].schemaName).toBe('ValidateUrl')
+        expect(result.result.endpoints['/validate-url/:id'].method).toBe('GET')
+        expect(result.result.endpoints['/validate-url/:id'].path).toBe('/validate-url/:id')
+        expect(result.result.endpoints['/validate-url/:id'].isAuthenticated).toBe(false)
+
+        expect(result.result.endpoints['/validate-headers']).toBeDefined()
+        expect(result.result.endpoints['/validate-headers'].schema).toStrictEqual(schema)
+        expect(result.result.endpoints['/validate-headers'].schemaName).toBe('ValidateHeaders')
+        expect(result.result.endpoints['/validate-headers'].method).toBe('GET')
+        expect(result.result.endpoints['/validate-headers'].path).toBe('/validate-headers')
+        expect(result.result.endpoints['/validate-headers'].isAuthenticated).toBe(false)
+
+        expect(result.result.endpoints['/validate-body']).toBeDefined()
+        expect(result.result.endpoints['/validate-body'].schema).toStrictEqual(schema)
+        expect(result.result.endpoints['/validate-body'].schemaName).toBe('ValidateBody')
+        expect(result.result.endpoints['/validate-body'].method).toBe('POST')
+        expect(result.result.endpoints['/validate-body'].path).toBe('/validate-body')
+        expect(result.result.endpoints['/validate-body'].isAuthenticated).toBe(false)
+
+        expect(result.result.endpoints['/mock']).toBeUndefined()
+        expect(result.result.endpoints['/mock/:id']).toBeUndefined()
+      })
+    })
+  })
+
   describe('Validation errors', () => {
     it('Should validate query', async () => {
       await usingAsync(await createValidateApi(), async ({ client }) => {

package/src/validate.ts

@@ -31,7 +31,7 @@ export const Validate =
 
     const validator = new SchemaValidator(schema, { coerceTypes: true, strict: false })
 
-    return async (args: RequestActionOptions<T>): Promise<ActionResult<T>> => {
+    const wrapped = async (args: RequestActionOptions<T>): Promise<ActionResult<T>> => {
       const anyArgs = args as any
       let body!: any
       const { headers } = anyArgs
@@ -62,4 +62,9 @@ export const Validate =
         getBody: () => Promise.resolve(body),
       })
     }
+
+    wrapped.schema = schema
+    wrapped.schemaName = validationOptions.schemaName
+
+    return wrapped
   }