@terreno/mcp 0.25.0 → 0.26.0

package/src/docs/versioned/0.25.0/reference/generated/api/classes/OpenApiMiddlewareBuilder.md

@@ -0,0 +1,577 @@
+A fluent builder for constructing OpenAPI middleware.
+
+This class provides a chainable API for defining OpenAPI documentation
+for Express routes. It supports defining tags, summaries, descriptions,
+request bodies, responses, and parameters.
+
+The builder pattern allows for flexible, readable configuration that
+produces middleware compatible with the express-openapi-validator library.
+
+## Example
+
+```typescript
+const middleware = new OpenApiMiddlewareBuilder(options)
+  .withTags(["users"])
+  .withSummary("Create a new user")
+  .withRequestBody<{name: string; email: string}>({
+    name: {type: "string", required: true},
+    email: {type: "string", format: "email", required: true},
+  })
+  .withResponse<{id: string; name: string}>(201, {
+    id: {type: "string"},
+    name: {type: "string"},
+  })
+  .build();
+```
+
+## Constructors
+
+### Constructor
+
+> **new OpenApiMiddlewareBuilder**(`options`): `OpenApiMiddlewareBuilder`
+
+Creates a new OpenApiMiddlewareBuilder instance.
+
+#### Parameters
+
+##### options
+
+`Partial`\<[`ModelRouterOptions`](../interfaces/ModelRouterOptions.md)\<`unknown`\>\>
+
+Router options containing the OpenAPI path configuration
+
+#### Returns
+
+`OpenApiMiddlewareBuilder`
+
+## Methods
+
+### build()
+
+> **build**(): `any`
+
+Builds and returns the OpenAPI middleware.
+
+This method finalizes the configuration and returns Express middleware
+that integrates with the OpenAPI documentation system. If no OpenAPI
+path is configured in options, returns a no-op middleware.
+
+If validation was enabled via `withValidation()`, returns an array
+of middleware: [openApiDocMiddleware, validationMiddleware].
+
+Default error responses (400, 401, 403, 404, 405) are automatically
+merged with the configured responses.
+
+#### Returns
+
+`any`
+
+Express middleware function(s) for OpenAPI documentation and optional validation
+
+#### Example
+
+```typescript
+const middleware = builder
+  .withTags(["users"])
+  .withResponse(200, {id: {type: "string"}})
+  .build();
+
+router.get("/users/:id", middleware, getUserHandler);
+```
+
+***
+
+### buildWithSchemas()
+
+> **buildWithSchemas**(): [`OpenApiBuildResult`](../interfaces/OpenApiBuildResult.md)
+
+Builds and returns the OpenAPI middleware along with schemas.
+
+This method is useful when you want to use asyncHandler's integrated
+validation instead of separate validation middleware.
+
+#### Returns
+
+[`OpenApiBuildResult`](../interfaces/OpenApiBuildResult.md)
+
+Object containing middleware and schemas
+
+#### Example
+
+```typescript
+const {middleware, bodySchema} = createOpenApiBuilder(options)
+  .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+  .buildWithSchemas();
+
+router.post("/users", middleware, asyncHandler(async (req, res) => {
+  // handler code
+}, {bodySchema, validate: true}));
+```
+
+***
+
+### withArrayResponse()
+
+> **withArrayResponse**\<`T`\>(`statusCode`, `itemSchema`, `options?`): `this`
+
+Adds an array response definition to the OpenAPI operation.
+
+Use this method when the response is an array of objects rather
+than a single object.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+Type representing the structure of each array item
+
+#### Parameters
+
+##### statusCode
+
+`number`
+
+HTTP status code for this response
+
+##### itemSchema
+
+\{ \[K in string \| number \| symbol\]: OpenApiSchemaProperty \}
+
+Schema for each item in the response array
+
+##### options?
+
+Optional configuration for the response
+
+###### description?
+
+`string`
+
+Description of the response (default: "Success")
+
+###### mediaType?
+
+`string`
+
+Media type for the response (default: "application/json")
+
+#### Returns
+
+`this`
+
+The builder instance for chaining
+
+#### Example
+
+```typescript
+builder.withArrayResponse<{id: string; name: string}>(200, {
+  id: {type: "string"},
+  name: {type: "string"},
+}, {description: "List of users"});
+```
+
+***
+
+### withDescription()
+
+> **withDescription**(`description`): `this`
+
+Sets the description for the OpenAPI operation.
+
+The description provides detailed information about the operation,
+including usage notes, examples, and caveats.
+
+#### Parameters
+
+##### description
+
+`string`
+
+Detailed description of the operation
+
+#### Returns
+
+`this`
+
+The builder instance for chaining
+
+#### Example
+
+```typescript
+builder.withDescription("Retrieves a user by their unique identifier. Returns 404 if not found.");
+```
+
+***
+
+### withOperationId()
+
+> **withOperationId**(`operationId`): `this`
+
+Sets an explicit `operationId` for the OpenAPI operation.
+
+The `operationId` is a unique string used to identify an operation. Client and SDK
+generators (e.g. RTK Query codegen) derive generated function and hook names from it,
+so setting it keeps generated names stable and readable for routes whose URL path would
+otherwise produce unwieldy names (e.g. deeply nested routes). It must be unique across
+the whole OpenAPI document.
+
+#### Parameters
+
+##### operationId
+
+`string`
+
+Unique operation identifier (e.g. "getUserStats")
+
+#### Returns
+
+`this`
+
+The builder instance for chaining
+
+#### Example
+
+```typescript
+builder.withOperationId("getUserStats");
+```
+
+***
+
+### withPathParameter()
+
+> **withPathParameter**(`name`, `schema`, `options?`): `this`
+
+Adds a path parameter to the OpenAPI operation.
+
+Path parameters are embedded in the URL path (e.g., `/users/:id`).
+Path parameters are always required per OpenAPI specification.
+
+#### Parameters
+
+##### name
+
+`string`
+
+Name of the path parameter (must match the route parameter)
+
+##### schema
+
+[`OpenApiSchemaProperty`](../interfaces/OpenApiSchemaProperty.md)
+
+Schema defining the parameter's type and format
+
+##### options?
+
+Optional configuration for the parameter
+
+###### description?
+
+`string`
+
+Human-readable description of the parameter
+
+#### Returns
+
+`this`
+
+The builder instance for chaining
+
+#### Example
+
+```typescript
+builder.withPathParameter("id", {type: "string", format: "uuid"}, {
+  description: "Unique identifier of the user",
+});
+```
+
+***
+
+### withQueryParameter()
+
+> **withQueryParameter**(`name`, `schema`, `options?`): `this`
+
+Adds a query parameter to the OpenAPI operation.
+
+Query parameters are passed in the URL query string (e.g., `?limit=10`).
+
+#### Parameters
+
+##### name
+
+`string`
+
+Name of the query parameter
+
+##### schema
+
+[`OpenApiSchemaProperty`](../interfaces/OpenApiSchemaProperty.md)
+
+Schema defining the parameter's type and format
+
+##### options?
+
+Optional configuration for the parameter
+
+###### description?
+
+`string`
+
+Human-readable description of the parameter
+
+###### required?
+
+`boolean`
+
+Whether the parameter is required (default: false)
+
+#### Returns
+
+`this`
+
+The builder instance for chaining
+
+#### Example
+
+```typescript
+builder.withQueryParameter("limit", {type: "number"}, {
+  required: false,
+  description: "Maximum number of results to return",
+});
+```
+
+***
+
+### withRequestBody()
+
+> **withRequestBody**\<`T`\>(`schema`, `options?`): `this`
+
+Sets the request body schema for the OpenAPI operation.
+
+Properties marked with `required: true` will be added to the schema's
+required array automatically.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+Type representing the request body structure
+
+#### Parameters
+
+##### schema
+
+\{ \[K in string \| number \| symbol\]: OpenApiSchemaProperty \}
+
+Object mapping property names to their OpenAPI schema definitions
+
+##### options?
+
+Optional configuration for the request body
+
+###### mediaType?
+
+`string`
+
+Media type for the request body (default: "application/json")
+
+###### required?
+
+`boolean`
+
+Whether the request body itself is required (default: true)
+
+#### Returns
+
+`this`
+
+The builder instance for chaining
+
+#### Example
+
+```typescript
+builder.withRequestBody<{name: string; age: number}>({
+  name: {type: "string", description: "User name", required: true},
+  age: {type: "number", description: "User age"},
+});
+```
+
+***
+
+### withResponse()
+
+> **withResponse**\<`T`\>(`statusCode`, `schema`, `options?`): `this`
+
+Adds a response definition to the OpenAPI operation.
+
+Can accept either an object schema or a simple string description
+for responses without a body (e.g., 204 No Content).
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+Type representing the response body structure
+
+#### Parameters
+
+##### statusCode
+
+`number`
+
+HTTP status code for this response
+
+##### schema
+
+`string` \| \{ \[K in string \| number \| symbol\]: OpenApiSchemaProperty \}
+
+Either an object schema or a description string
+
+##### options?
+
+Optional configuration for the response
+
+###### description?
+
+`string`
+
+Description of the response (default: "Success")
+
+###### mediaType?
+
+`string`
+
+Media type for the response (default: "application/json")
+
+#### Returns
+
+`this`
+
+The builder instance for chaining
+
+#### Example
+
+```typescript
+// Response with body
+builder.withResponse<{id: string}>(200, {
+  id: {type: "string", description: "Created resource ID"},
+}, {description: "Resource created successfully"});
+
+// Response without body
+builder.withResponse(204, "No content");
+```
+
+***
+
+### withSummary()
+
+> **withSummary**(`summary`): `this`
+
+Sets the summary for the OpenAPI operation.
+
+The summary is a brief description shown in API documentation listings.
+
+#### Parameters
+
+##### summary
+
+`string`
+
+Short description of the operation
+
+#### Returns
+
+`this`
+
+The builder instance for chaining
+
+#### Example
+
+```typescript
+builder.withSummary("Get user by ID");
+```
+
+***
+
+### withTags()
+
+> **withTags**(`tags`): `this`
+
+Sets the tags for the OpenAPI operation.
+
+Tags are used to group operations in the API documentation.
+
+#### Parameters
+
+##### tags
+
+`string`[]
+
+Array of tag names
+
+#### Returns
+
+`this`
+
+The builder instance for chaining
+
+#### Example
+
+```typescript
+builder.withTags(["users", "authentication"]);
+```
+
+***
+
+### withValidation()
+
+> **withValidation**(`options?`): `this`
+
+Enables runtime validation for this route.
+
+When enabled, the built middleware will validate incoming requests
+against the documented schema before the handler runs.
+
+#### Parameters
+
+##### options?
+
+Optional configuration for validation
+
+###### body?
+
+`boolean`
+
+Enable body validation (default: true if request body is defined)
+
+###### enabled?
+
+`boolean`
+
+Override the global validation enabled setting
+
+###### query?
+
+`boolean`
+
+Enable query parameter validation (default: true if query params are defined)
+
+#### Returns
+
+`this`
+
+The builder instance for chaining
+
+#### Example
+
+```typescript
+createOpenApiBuilder(options)
+  .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+  .withValidation() // Enable validation
+  .build();
+```