@furystack/rest-service 12.2.0 → 12.3.0

package/src/openapi/generate-openapi-document.ts

@@ -0,0 +1,198 @@
+import type {
+  ApiDocumentMetadata,
+  ApiEndpointDefinition,
+  ApiEndpointSchema,
+  Method,
+  OpenApiDocument,
+  Operation,
+  ParameterObject,
+  RequestBodyObject,
+} from '@furystack/rest'
+
+const PATH_ITEM_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'] as const
+type PathItemMethod = (typeof PATH_ITEM_METHODS)[number]
+
+const isPathItemMethod = (method: string): method is PathItemMethod =>
+  PATH_ITEM_METHODS.includes(method as PathItemMethod)
+
+type SchemaDefinition = {
+  properties?: Record<string, unknown>
+  required?: string[]
+  [key: string]: unknown
+}
+
+type SchemaWithDefinitions = {
+  definitions?: Record<string, SchemaDefinition>
+  [key: string]: unknown
+}
+
+const getSubSchema = (
+  schema: unknown,
+  schemaName: string,
+  property: string,
+): { subSchema: unknown; isRequired: boolean } | undefined => {
+  const typedSchema = schema as SchemaWithDefinitions | undefined
+  if (!typedSchema?.definitions) return undefined
+
+  const definition = typedSchema.definitions[schemaName]
+  if (!definition?.properties?.[property]) return undefined
+
+  return {
+    subSchema: definition.properties[property],
+    isRequired: definition.required?.includes(property) ?? false,
+  }
+}
+
+/**
+ * Converts a FuryStack API schema to an OpenAPI 3.1 compatible document.
+ * Preserves metadata from ApiEndpointDefinition and ApiDocumentMetadata when available.
+ */
+export const generateOpenApiDocument = ({
+  api,
+  title = 'FuryStack API',
+  description = 'API documentation generated from FuryStack API schema',
+  version = '1.0.0',
+  metadata,
+}: {
+  api: ApiEndpointSchema['endpoints']
+  title?: string
+  description?: string
+  version?: string
+  metadata?: ApiDocumentMetadata
+}): OpenApiDocument => {
+  const doc: OpenApiDocument = {
+    openapi: '3.1.0',
+    info: {
+      title,
+      version,
+      description,
+      ...(metadata?.summary ? { summary: metadata.summary } : {}),
+      ...(metadata?.termsOfService ? { termsOfService: metadata.termsOfService } : {}),
+      ...(metadata?.contact ? { contact: metadata.contact } : {}),
+      ...(metadata?.license ? { license: metadata.license } : {}),
+    },
+    jsonSchemaDialect: 'https://spec.openapis.org/oas/3.1/dialect/base',
+    servers: metadata?.servers ?? [{ url: '/' }],
+    tags: metadata?.tags ?? [],
+    ...(metadata?.externalDocs ? { externalDocs: metadata.externalDocs } : {}),
+    paths: {},
+    components: {
+      schemas: {},
+      securitySchemes: metadata?.securitySchemes ?? {
+        cookieAuth: {
+          type: 'apiKey',
+          in: 'cookie',
+          name: 'session',
+        },
+      },
+    },
+  }
+
+  const defaultSchemeNames = metadata?.securitySchemes ? Object.keys(metadata.securitySchemes) : ['cookieAuth']
+
+  for (const [methodKey, paths] of Object.entries(api) as Array<[Method, Record<string, ApiEndpointDefinition>]>) {
+    for (const [path, definition] of Object.entries(paths)) {
+      const normalizedPath = path.replace(/:([^/]+)/g, '{$1}')
+      if (!doc.paths![normalizedPath]) {
+        doc.paths![normalizedPath] = {}
+      }
+
+      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' },
+      }))
+
+      const queryInfo = getSubSchema(definition.schema, definition.schemaName, 'query')
+      if (queryInfo) {
+        const querySchema = queryInfo.subSchema as { properties?: Record<string, unknown>; required?: string[] }
+        if (querySchema?.properties) {
+          for (const [paramName, paramSchema] of Object.entries(querySchema.properties)) {
+            parameters.push({
+              name: paramName,
+              in: 'query',
+              required: querySchema.required?.includes(paramName) ?? false,
+              schema: paramSchema as object,
+            })
+          }
+        }
+      }
+
+      const headerInfo = getSubSchema(definition.schema, definition.schemaName, 'headers')
+      if (headerInfo) {
+        const headerSchema = headerInfo.subSchema as { properties?: Record<string, unknown>; required?: string[] }
+        if (headerSchema?.properties) {
+          for (const [headerName, headerParamSchema] of Object.entries(headerSchema.properties)) {
+            parameters.push({
+              name: headerName,
+              in: 'header',
+              required: headerSchema.required?.includes(headerName) ?? false,
+              schema: headerParamSchema as object,
+            })
+          }
+        }
+      }
+
+      const operationSecurity = definition.securitySchemes
+        ? definition.securitySchemes.map((name) => ({ [name]: [] }))
+        : definition.isAuthenticated
+          ? defaultSchemeNames.map((name) => ({ [name]: [] }))
+          : []
+
+      const method = methodKey.toLowerCase()
+      const operation: Operation = {
+        summary: definition.summary ?? `${methodKey} ${path}`,
+        description: definition.description ?? `Endpoint for ${path}`,
+        operationId: `${method}${path.replace(/\//g, '_').replace(/:/g, '').replace(/-/g, '_')}`,
+        security: operationSecurity,
+        parameters,
+        ...(definition.tags?.length ? { tags: definition.tags } : {}),
+        ...(definition.deprecated ? { deprecated: true } : {}),
+        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' },
+        },
+      }
+
+      const bodyInfo = getSubSchema(definition.schema, definition.schemaName, 'body')
+      if (bodyInfo) {
+        const requestBody: RequestBodyObject = {
+          required: bodyInfo.isRequired,
+          content: {
+            'application/json': {
+              schema: bodyInfo.subSchema as object,
+            },
+          },
+        }
+        operation.requestBody = requestBody
+      }
+
+      if (definition.schema && definition.schemaName) {
+        doc.components!.schemas![definition.schemaName] = definition.schema
+      }
+
+      const pathItem = doc.paths![normalizedPath]
+      if (isPathItemMethod(method)) {
+        pathItem[method] = operation
+      }
+    }
+  }
+
+  return doc
+}
+
+/** @deprecated Use generateOpenApiDocument instead */
+export const generateSwaggerJsonFromApiSchema = generateOpenApiDocument

package/src/openapi/openapi-round-trip.advanced-api.json

@@ -0,0 +1,363 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Advanced Pet Store API",
+    "version": "2.1.0",
+    "description": "A feature-rich API exercising all OpenAPI 3.1 constructs",
+    "summary": "Pet store with advanced features",
+    "termsOfService": "https://example.com/terms",
+    "contact": {
+      "name": "API Support",
+      "url": "https://example.com/support",
+      "email": "support@example.com"
+    },
+    "license": {
+      "name": "MIT",
+      "identifier": "MIT"
+    }
+  },
+  "externalDocs": {
+    "description": "Full documentation",
+    "url": "https://example.com/docs"
+  },
+  "servers": [
+    {
+      "url": "https://{environment}.example.com/api/{version}",
+      "description": "Main server",
+      "variables": {
+        "environment": {
+          "default": "production",
+          "enum": ["production", "staging", "development"],
+          "description": "Server environment"
+        },
+        "version": {
+          "default": "v2"
+        }
+      }
+    }
+  ],
+  "tags": [
+    { "name": "pets", "description": "Pet operations" },
+    {
+      "name": "store",
+      "description": "Store operations",
+      "externalDocs": { "url": "https://example.com/docs/store" }
+    }
+  ],
+  "security": [{ "bearerAuth": [] }],
+  "paths": {
+    "/pets": {
+      "get": {
+        "operationId": "listPets",
+        "summary": "List all pets",
+        "description": "Returns a paginated list of pets with optional filtering",
+        "tags": ["pets"],
+        "security": [],
+        "parameters": [
+          { "$ref": "#/components/parameters/LimitParam" },
+          { "$ref": "#/components/parameters/OffsetParam" },
+          {
+            "name": "status",
+            "in": "query",
+            "schema": { "type": "string", "enum": ["available", "pending", "sold"] }
+          },
+          {
+            "name": "tags",
+            "in": "query",
+            "schema": { "type": "array", "items": { "type": "string" } }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "items": {
+                      "type": "array",
+                      "items": { "$ref": "#/components/schemas/Pet" }
+                    },
+                    "total": { "type": "integer" }
+                  },
+                  "required": ["items", "total"]
+                }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/BadRequest" }
+        }
+      },
+      "post": {
+        "operationId": "createPet",
+        "summary": "Create a pet",
+        "tags": ["pets"],
+        "requestBody": {
+          "required": true,
+          "description": "Pet to create",
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/CreatePetRequest" }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Pet created",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Pet" }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/BadRequest" }
+        }
+      }
+    },
+    "/pets/{petId}": {
+      "get": {
+        "operationId": "getPet",
+        "summary": "Get a pet by ID",
+        "tags": ["pets"],
+        "parameters": [
+          {
+            "name": "petId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Pet" }
+              }
+            }
+          },
+          "404": { "$ref": "#/components/responses/NotFound" }
+        }
+      },
+      "patch": {
+        "operationId": "updatePet",
+        "summary": "Update a pet",
+        "tags": ["pets"],
+        "parameters": [
+          {
+            "name": "petId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": { "type": "string" },
+                  "status": { "type": "string", "enum": ["available", "pending", "sold"] },
+                  "tag": { "type": ["string", "null"] }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Pet updated",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Pet" }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deletePet",
+        "summary": "Delete a pet",
+        "tags": ["pets"],
+        "deprecated": true,
+        "description": "Use archive endpoint instead",
+        "parameters": [
+          {
+            "name": "petId",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Pet deleted"
+          }
+        }
+      }
+    },
+    "/store/inventory": {
+      "get": {
+        "operationId": "getInventory",
+        "summary": "Returns pet inventories",
+        "tags": ["store"],
+        "parameters": [
+          {
+            "name": "X-Request-Id",
+            "in": "header",
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Inventory map",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "additionalProperties": { "type": "integer" }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/store/orders": {
+      "post": {
+        "operationId": "placeOrder",
+        "summary": "Place an order",
+        "tags": ["store"],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/OrderRequest" }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Order placed",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Order" }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Pet": {
+        "allOf": [
+          { "$ref": "#/components/schemas/CreatePetRequest" },
+          {
+            "type": "object",
+            "properties": {
+              "id": { "type": "string" },
+              "createdAt": { "type": "string" },
+              "status": { "type": "string", "enum": ["available", "pending", "sold"] }
+            },
+            "required": ["id", "createdAt", "status"]
+          }
+        ]
+      },
+      "CreatePetRequest": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "tag": { "type": ["string", "null"] },
+          "category": { "$ref": "#/components/schemas/Category" }
+        },
+        "required": ["name"]
+      },
+      "Category": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "integer" },
+          "name": { "type": "string" }
+        },
+        "required": ["id", "name"]
+      },
+      "Order": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "petId": { "type": "string" },
+          "quantity": { "type": "integer" },
+          "status": {
+            "oneOf": [{ "const": "placed" }, { "const": "approved" }, { "const": "delivered" }]
+          },
+          "shipDate": { "type": ["string", "null"] },
+          "complete": { "type": "boolean" }
+        },
+        "required": ["id", "petId", "quantity", "status", "complete"]
+      },
+      "OrderRequest": {
+        "type": "object",
+        "properties": {
+          "petId": { "type": "string" },
+          "quantity": { "type": "integer" }
+        },
+        "required": ["petId", "quantity"]
+      },
+      "Error": {
+        "type": "object",
+        "properties": {
+          "code": { "type": "integer" },
+          "message": { "type": "string" }
+        },
+        "required": ["code", "message"]
+      }
+    },
+    "parameters": {
+      "LimitParam": {
+        "name": "limit",
+        "in": "query",
+        "description": "Maximum number of items to return",
+        "schema": { "type": "integer" }
+      },
+      "OffsetParam": {
+        "name": "offset",
+        "in": "query",
+        "description": "Number of items to skip",
+        "schema": { "type": "integer" }
+      }
+    },
+    "responses": {
+      "BadRequest": {
+        "description": "Bad request",
+        "content": {
+          "application/json": {
+            "schema": { "$ref": "#/components/schemas/Error" }
+          }
+        }
+      },
+      "NotFound": {
+        "description": "Resource not found",
+        "content": {
+          "application/json": {
+            "schema": { "$ref": "#/components/schemas/Error" }
+          }
+        }
+      }
+    },
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      },
+      "apiKey": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-API-Key"
+      }
+    }
+  }
+}

package/src/openapi/openapi-round-trip.crud-api.json

@@ -0,0 +1,115 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "CRUD API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "operationId": "listUsers",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "id": { "type": "string" },
+                      "name": { "type": "string" },
+                      "email": { "type": "string" }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "createUser",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": { "type": "string" },
+                  "email": { "type": "string" }
+                },
+                "required": ["name", "email"]
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": { "type": "string" },
+                    "name": { "type": "string" },
+                    "email": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/users/{id}": {
+      "get": {
+        "operationId": "getUser",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": { "type": "string" },
+                    "name": { "type": "string" },
+                    "email": { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteUser",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Deleted"
+          }
+        }
+      }
+    }
+  }
+}