@autobe/agent
Version:
AI backend server code generator
469 lines (468 loc) • 411 kB
JavaScript
"use strict";
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
var desc = Object.getOwnPropertyDescriptor(m, k);
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
desc = { enumerable: true, get: function() { return m[k]; } };
}
Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
o["default"] = v;
});
var __importStar = (this && this.__importStar) || (function () {
var ownKeys = function(o) {
ownKeys = Object.getOwnPropertyNames || function (o) {
var ar = [];
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
return ar;
};
return ownKeys(o);
};
return function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
__setModuleDefault(result, mod);
return result;
};
})();
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
return new (P || (P = Promise))(function (resolve, reject) {
function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
step((generator = generator.apply(thisArg, _arguments || [])).next());
});
};
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.orchestrateInterfaceOperationReview = orchestrateInterfaceOperationReview;
const __typia_transform__validateReport = __importStar(require("typia/lib/internal/_validateReport.js"));
const __typia_transform__llmApplicationFinalize = __importStar(require("typia/lib/internal/_llmApplicationFinalize.js"));
const typia_1 = __importDefault(require("typia"));
const uuid_1 = require("uuid");
const AutoBePreliminaryController_1 = require("../common/AutoBePreliminaryController");
const transformInterfaceOperationReviewHistory_1 = require("./histories/transformInterfaceOperationReviewHistory");
const OperationValidator_1 = require("./utils/OperationValidator");
function orchestrateInterfaceOperationReview(ctx, operations, progress) {
return __awaiter(this, void 0, void 0, function* () {
try {
return yield process(ctx, operations, progress);
}
catch (_a) {
++progress.completed;
return [];
}
});
}
function process(ctx, operations, progress) {
return __awaiter(this, void 0, void 0, function* () {
var _a;
const files = (_a = ctx.state().prisma) === null || _a === void 0 ? void 0 : _a.result.data.files;
const preliminary = new AutoBePreliminaryController_1.AutoBePreliminaryController({
application: {
version: "3.1",
components: {
schemas: {
"IAutoBeInterfaceOperationReviewApplication.IProps": {
type: "object",
properties: {
thinking: {
type: "string",
description: "Think before you act.\n\nBefore requesting preliminary data or completing your task, reflect on your\ncurrent state and explain your reasoning:\n\nFor preliminary requests (getAnalysisFiles, getPrismaSchemas, etc.):\n- What critical information is missing that you don't already have?\n- Why do you need it specifically right now?\n- Be brief - state the gap, don't list everything you have.\n\nFor completion (complete):\n- What key assets did you acquire?\n- What did you accomplish?\n- Why is it sufficient to complete?\n- Summarize - don't enumerate every single item.\n\nThis reflection helps you avoid duplicate requests and premature completion."
},
request: {
oneOf: [
{
$ref: "#/components/schemas/IAutoBePreliminaryGetAnalysisFiles"
},
{
$ref: "#/components/schemas/IAutoBePreliminaryGetPrismaSchemas"
},
{
$ref: "#/components/schemas/IAutoBeInterfaceOperationReviewApplication.IComplete"
}
],
discriminator: {
propertyName: "type",
mapping: {
getAnalysisFiles: "#/components/schemas/IAutoBePreliminaryGetAnalysisFiles",
getPrismaSchemas: "#/components/schemas/IAutoBePreliminaryGetPrismaSchemas",
complete: "#/components/schemas/IAutoBeInterfaceOperationReviewApplication.IComplete"
}
},
description: "Type discriminator for the request.\n\nDetermines which action to perform: preliminary data retrieval\n(getAnalysisFiles, getPrismaSchemas) or final operation review\n(complete). When preliminary returns empty array, that type is removed\nfrom the union, physically preventing repeated calls."
}
},
required: [
"thinking",
"request"
]
},
IAutoBePreliminaryGetAnalysisFiles: {
type: "object",
properties: {
type: {
"const": "getAnalysisFiles",
description: "Type discriminator for the request.\n\nDetermines which action to perform: preliminary data retrieval or actual\ntask execution. Value \"getAnalysisFiles\" indicates this is a preliminary\ndata request for analysis files."
},
fileNames: {
type: "array",
items: {
type: "string"
},
minItems: 1,
description: "List of analysis file names to retrieve.\n\nFile names from the analyze phase containing requirements, use cases, and\nbusiness logic documentation.\n\nCRITICAL: DO NOT request the same file names that you have already\nrequested in previous calls."
}
},
required: [
"type",
"fileNames"
],
description: "Request to retrieve requirements analysis files for context.\n\nThis type is used in the preliminary phase to request specific analysis files\nthat provide business requirements and domain context."
},
IAutoBePreliminaryGetPrismaSchemas: {
type: "object",
properties: {
type: {
"const": "getPrismaSchemas",
description: "Type discriminator for the request.\n\nDetermines which action to perform: preliminary data retrieval or actual\ntask execution. Value \"getPrismaSchemas\" indicates this is a preliminary\ndata request for Prisma schemas."
},
schemaNames: {
type: "array",
items: {
type: "string"
},
minItems: 1,
description: "List of Prisma table names to retrieve.\n\nTable names from the Prisma schema file representing database entities\n(e.g., \"user\", \"post\", \"comment\").\n\nCRITICAL: DO NOT request the same schema names that you have already\nrequested in previous calls."
}
},
required: [
"type",
"schemaNames"
],
description: "Request to retrieve Prisma database schema definitions for context.\n\nThis type is used in the preliminary phase to request specific Prisma table\nschemas needed for generating type-safe API operations."
},
"IAutoBeInterfaceOperationReviewApplication.IComplete": {
type: "object",
properties: {
type: {
"const": "complete",
description: "Type discriminator for the request.\n\nDetermines which action to perform: preliminary data retrieval or actual\ntask execution. Value \"complete\" indicates this is the final task\nexecution request."
},
think: {
$ref: "#/components/schemas/IAutoBeInterfaceOperationReviewApplication.IThink",
description: "Comprehensive thinking process for API operation review.\n\nEncapsulates the agent's analytical review findings and actionable\nimprovement plan. This structured thinking process ensures systematic\nevaluation of API operations against AutoBE's quality standards before\ngenerating the final enhanced operations."
},
content: {
type: "array",
items: {
$ref: "#/components/schemas/AutoBeOpenApi.IOperation"
},
description: "Production-ready operations with all critical issues resolved.\n\nFinal API operations after systematic enhancement:\n\n- **Security Fixes Applied**: All authentication boundaries enforced,\n sensitive data removed from responses, proper authorization\n implemented\n- **Logic Corrections Made**: Return types match operation intent, HTTP\n methods align with semantics, parameters properly utilized\n- **Schema Alignment Verified**: All fields exist in Prisma schema, types\n correctly mapped, relationships properly defined\n- **Quality Improvements Added**: Enhanced documentation, format\n specifications, validation rules, consistent naming patterns\n\nIf no issues were found during review, this contains the exact original\noperations unchanged. These operations are validated and ready for schema\ngeneration and subsequent implementation phases."
}
},
required: [
"type",
"think",
"content"
],
description: "Request to review and validate API operations.\n\nExecutes systematic operation review for quality and correctness, analyzing\nsecurity vulnerabilities, schema compliance, logical consistency, and\nstandard adherence. Outputs structured thinking process and enhanced\noperations."
},
"IAutoBeInterfaceOperationReviewApplication.IThink": {
type: "object",
properties: {
review: {
type: "string",
description: "Comprehensive review analysis with prioritized findings.\n\nSystematic assessment organized by severity levels (CRITICAL, HIGH,\nMEDIUM, LOW):\n\n- **Security Analysis**: Authentication boundary violations, exposed\n passwords/tokens, unauthorized data access patterns, SQL injection\n risks\n- **Logic Validation**: Return type consistency (list operations returning\n arrays, single retrieval returning single items), HTTP method semantics\n alignment, parameter usage verification\n- **Schema Compliance**: Field existence in Prisma schema, type accuracy,\n relationship validity, required field handling\n- **Quality Assessment**: Documentation completeness, naming conventions,\n error handling patterns, pagination standards\n\nEach finding includes specific examples, current vs expected behavior,\nand concrete fix recommendations. Critical security issues and logical\ncontradictions are highlighted for immediate attention."
},
plan: {
type: "string",
description: "Prioritized action plan for identified issues.\n\nStructured improvement strategy categorized by severity:\n\n- **Immediate Actions (CRITICAL)**: Security vulnerabilities that must be\n fixed before production (password exposure, missing authorization,\n authentication bypass risks)\n- **Required Fixes (HIGH)**: Functional issues affecting API correctness\n (wrong return types, missing required fields, schema mismatches)\n- **Recommended Improvements (MEDIUM)**: Quality enhancements for better\n API design (validation rules, format specifications, consistency)\n- **Optional Enhancements (LOW)**: Documentation and usability improvements\n\nIf all operations pass review without issues, contains: \"No improvements\nrequired. All operations meet AutoBE standards.\"\n\nEach action item includes the specific operation path, the exact change\nneeded, and the rationale for the modification."
}
},
required: [
"review",
"plan"
],
description: "Structured thinking process for operation review.\n\nContains analytical review findings and improvement action plan organized\nfor systematic enhancement of the operations."
},
"AutoBeOpenApi.IOperation": {
type: "object",
properties: {
specification: {
type: "string",
description: "Specification of the API operation.\n\nBefore defining the API operation interface, please describe what you're\nplanning to write in this `specification` field.\n\nThe specification must be fully detailed and clear, so that anyone can\nunderstand the purpose and functionality of the API operation and its\nrelated components (e.g., {@link path}, {@link parameters},\n{@link requestBody}).\n\nIMPORTANT: The specification MUST identify which Prisma DB table this\noperation is associated with, helping ensure complete coverage of all\ndatabase entities."
},
authorizationType: {
oneOf: [
{
type: "null"
},
{
"const": "login"
},
{
"const": "join"
},
{
"const": "refresh"
}
],
description: "Authorization type of the API operation.\n\n- `\"login\"`: User login operations that validate credentials\n- `\"join\"`: User registration operations that create accounts\n- `\"refresh\"`: Token refresh operations that renew access tokens\n- `null`: All other operations (CRUD, business logic, etc.)\n\nUse authentication values only for credential validation, user\nregistration, or token refresh operations. Use `null` for all other\nbusiness operations.\n\nExamples:\n\n- `/auth/login` \u2192 `\"login\"`\n- `/auth/register` \u2192 `\"join\"`\n- `/auth/refresh` \u2192 `\"refresh\"`\n- `/auth/validate` \u2192 `null`\n- `/users/{id}`, `/shoppings/customers/sales/cancel`, \u2192 `null`"
},
description: {
type: "string",
description: "Detailed description about the API operation.\n\nIMPORTANT: This field MUST be extensively detailed and MUST reference the\ndescription comments from the related Prisma DB schema tables and\ncolumns. The description should be organized into MULTIPLE PARAGRAPHS\nseparated by line breaks to improve readability and comprehension.\n\nFor example, include separate paragraphs for:\n\n- The purpose and overview of the API operation\n- Security considerations and user permissions\n- Relationship to underlying database entities\n- Validation rules and business logic\n- Related API operations that might be used together with this one\n- Expected behavior and error handling\n\nWhen writing the description, be sure to incorporate the corresponding DB\nschema's description comments, matching the level of detail and style of\nthose comments. This ensures consistency between the API documentation\nand database structure.\n\nIf there's a dependency to other APIs, please describe the dependency API\noperation in this field with detailed reason. For example, if this API\noperation needs a pre-execution of other API operation, it must be\nexplicitly described.\n\n- `GET /shoppings/customers/sales` must be pre-executed to get entire list\n of summarized sales. Detailed sale information would be obtained by\n specifying the sale ID in the path parameter.\n\n**CRITICAL WARNING about soft delete keywords**: DO NOT use terms like\n\"soft delete\", \"soft-delete\", or similar variations in this description\nUNLESS the operation actually implements soft deletion. These keywords\ntrigger validation logic that expects a corresponding soft_delete_column\nto be specified. Only use these terms when you intend to implement soft\ndeletion (marking records as deleted without removing them from the\ndatabase).\n\nExample of problematic description: \u274C \"This would normally be a\nsoft-delete, but we intentionally perform permanent deletion here\" - This\ntriggers soft delete validation despite being a hard delete operation.\n\n> MUST be written in English. Never use other languages."
},
summary: {
type: "string",
description: "Short summary of the API operation.\n\nThis should be a concise description of the API operation, typically one\nsentence long. It should provide a quick overview of what the API does\nwithout going into too much detail.\n\nThis summary will be used in the OpenAPI documentation to give users a\nquick understanding of the API operation's purpose.\n\nIMPORTANT: The summary should clearly indicate which Prisma DB table this\noperation relates to, helping to ensure all tables have API coverage.\n\n**CRITICAL WARNING about soft delete keywords**: DO NOT use terms like\n\"soft delete\", \"soft-delete\", or similar variations in this summary\nUNLESS the operation actually implements soft deletion. These keywords\ntrigger validation logic that expects a corresponding soft_delete_column\nto be specified. Only use these terms when you intend to implement soft\ndeletion (marking records as deleted without removing them from the\ndatabase).\n\n> MUST be written in English. Never use other languages"
},
parameters: {
type: "array",
items: {
$ref: "#/components/schemas/AutoBeOpenApi.IParameter"
},
description: "List of path parameters.\n\nNote that, the {@link AutoBeOpenApi.IParameter.name identifier name} of\npath parameter must be corresponded to the\n{@link path API operation path}.\n\nFor example, if there's an API operation which has {@link path} of\n`/shoppings/customers/sales/{saleId}/questions/${questionId}/comments/${commentId}`,\nits list of {@link AutoBeOpenApi.IParameter.name path parameters} must be\nlike:\n\n- `saleId`\n- `questionId`\n- `commentId`"
},
requestBody: {
oneOf: [
{
type: "null"
},
{
$ref: "#/components/schemas/AutoBeOpenApi.IRequestBody"
}
],
description: "Request body of the API operation.\n\nDefines the payload structure for the request. Contains a description and\nschema reference to define the expected input data.\n\nShould be `null` for operations that don't require a request body, such\nas most \"get\" operations."
},
responseBody: {
oneOf: [
{
type: "null"
},
{
$ref: "#/components/schemas/AutoBeOpenApi.IResponseBody"
}
],
description: "Response body of the API operation.\n\nDefines the structure of the successful response data. Contains a\ndescription and schema reference for the returned data.\n\nShould be null for operations that don't return any data."
},
authorizationActor: {
oneOf: [
{
type: "null"
},
{
type: "string",
pattern: "^[a-z][a-zA-Z0-9]*$",
minLength: 1
}
],
description: "Authorization actor required to access this API operation.\n\nThis field specifies which user actor is allowed to access this endpoint.\nThe actor name must correspond exactly to the actual actors defined in\nyour system's Prisma schema.\n\n## Naming Convention\n\nActor names MUST use camelCase.\n\n## Actor-Based Path Convention\n\nWhen authorizationActor is specified, it should align with the path\nstructure:\n\n- If authorizationActor is \"admin\" \u2192 path might be \"/admin/resources/{id}\"\n- If authorizationActor is \"seller\" \u2192 path might be \"/seller/products\"\n- Special case: For user's own resources, use path prefix \"/my/\" regardless\n of actor\n\n## Important Guidelines\n\n- Set to `null` for public endpoints that require no authentication\n- Set to specific actor string for actor-restricted endpoints\n- The actor name MUST match exactly with the user type/actor defined in the\n database\n- This actor will be used by the Realize Agent to generate appropriate\n decorator and authorization logic in the provider functions\n- The controller will apply the corresponding authentication decorator\n based on this actor\n\n## Examples\n\n- `null` - Public endpoint, no authentication required\n- `\"user\"` - Any authenticated user can access\n- `\"admin\"` - Only admin users can access\n- `\"seller\"` - Only seller users can access\n- `\"moderator\"` - Only moderator users can access\n\nNote: The actual authentication/authorization implementation will be\nhandled by decorators at the controller level, and the provider function\nwill receive the authenticated user object with the appropriate type."
},
name: {
type: "string",
pattern: "^[a-z][a-zA-Z0-9]*$",
description: "Functional name of the API endpoint.\n\nThis is a semantic identifier that represents the primary function or\npurpose of the API endpoint. It serves as a canonical name that can be\nused for code generation, SDK method names, and internal references.\n\n## Reserved Word Restrictions\n\nCRITICAL: The name MUST NOT be a TypeScript/JavaScript reserved word, as\nit will be used as a class method name in generated code. Avoid names\nlike:\n\n- `delete`, `for`, `if`, `else`, `while`, `do`, `switch`, `case`, `break`\n- `continue`, `function`, `return`, `with`, `in`, `of`, `instanceof`\n- `typeof`, `void`, `var`, `let`, `const`, `class`, `extends`, `import`\n- `export`, `default`, `try`, `catch`, `finally`, `throw`, `new`\n- `super`, `this`, `null`, `true`, `false`, `async`, `await`\n- `yield`, `static`, `private`, `protected`, `public`, `implements`\n- `interface`, `package`, `enum`, `debugger`\n\nInstead, use alternative names for these operations:\n\n- Use `erase` instead of `delete`\n- Use `iterate` instead of `for`\n- Use `when` instead of `if`\n- Use `cls` instead of `class`\n\n## Standard Endpoint Names\n\nUse these conventional names based on the endpoint's primary function:\n\n- **`index`**: List/search operations that return multiple entities\n\n - Typically used with PATCH method for complex queries\n - Example: `PATCH /users` \u2192 `name: \"index\"`\n- **`at`**: Retrieve a specific entity by identifier\n\n - Typically used with GET method on single resource\n - Example: `GET /users/{userId}` \u2192 `name: \"at\"`\n- **`create`**: Create a new entity\n\n - Typically used with POST method\n - Example: `POST /users` \u2192 `name: \"create\"`\n- **`update`**: Update an existing entity\n\n - Typically used with PUT method\n - Example: `PUT /users/{userId}` \u2192 `name: \"update\"`\n- **`erase`**: Delete/remove an entity (NOT `delete` - reserved word!)\n\n - Typically used with DELETE method\n - Example: `DELETE /users/{userId}` \u2192 `name: \"erase\"`\n\n## Custom Endpoint Names\n\nFor specialized operations beyond basic CRUD, use descriptive verbs:\n\n- **`activate`**: Enable or turn on a feature/entity\n- **`deactivate`**: Disable or turn off a feature/entity\n- **`approve`**: Approve a request or entity\n- **`reject`**: Reject a request or entity\n- **`publish`**: Make content publicly available\n- **`archive`**: Move to archived state\n- **`restore`**: Restore from archived/deleted state\n- **`duplicate`**: Create a copy of an entity\n- **`transfer`**: Move ownership or change assignment\n- **`validate`**: Validate data or state\n- **`process`**: Execute a business process or workflow\n- **`export`**: Generate downloadable data\n- **`import`**: Process uploaded data\n\n## Naming Guidelines\n\n- MUST use camelCase naming convention\n- Use singular verb forms\n- Be concise but descriptive\n- Avoid abbreviations unless widely understood\n- Ensure the name clearly represents the endpoint's primary action\n- For nested resources, focus on the action rather than hierarchy\n- NEVER use JavaScript/TypeScript reserved words\n\nValid Examples:\n\n- `index`, `create`, `update`, `erase` (single word)\n- `updatePassword`, `cancelOrder`, `publishArticle` (camelCase)\n- `validateEmail`, `generateReport`, `exportData` (camelCase)\n\nInvalid Examples:\n\n- `update_password` (snake_case not allowed)\n- `UpdatePassword` (PascalCase not allowed)\n- `update-password` (kebab-case not allowed)\n\nPath to Name Examples:\n\n- `GET /shopping/orders/{orderId}/items` \u2192 `name: \"index\"` (lists items)\n- `POST /shopping/orders/{orderId}/cancel` \u2192 `name: \"cancel\"`\n- `PUT /users/{userId}/password` \u2192 `name: \"updatePassword\"`\n\n## Uniqueness Rule\n\nThe `name` must be unique within the API's accessor namespace. The\naccessor is formed by combining the path segments (excluding parameters)\nwith the operation name.\n\nAccessor formation:\n\n1. Extract non-parameter segments from the path (remove `{...}` parts)\n2. Join segments with dots\n3. Append the operation name\n\nExamples:\n\n- Path: `/shopping/sale/{saleId}/review/{reviewId}`, Name: `at` \u2192 Accessor:\n `shopping.sale.review.at`\n- Path: `/users/{userId}/posts`, Name: `index` \u2192 Accessor:\n `users.posts.index`\n- Path: `/auth/login`, Name: `signIn` \u2192 Accessor: `auth.login.signIn`\n\nEach accessor must be globally unique across the entire API. This ensures\noperations can be uniquely identified in generated SDKs and prevents\nnaming conflicts."
},
prerequisites: {
type: "array",
items: {
$ref: "#/components/schemas/AutoBeOpenApi.IPrerequisite"
},
description: "Prerequisites for this API operation.\n\nThe `prerequisites` field defines API operations that must be\nsuccessfully executed before this operation can be performed. This\ncreates an explicit dependency chain between API endpoints, ensuring\nproper execution order and data availability.\n\n## CRITICAL WARNING: Authentication Prerequisites\n\n**NEVER include authentication-related operations as prerequisites!**\nAuthentication is handled separately through the `authorizationActor`\nfield and should NOT be part of the prerequisite chain. Do NOT add\nprerequisites for:\n\n- Login endpoints\n- Token validation endpoints\n- User authentication checks\n- Permission verification endpoints\n\nPrerequisites are ONLY for business logic dependencies, NOT for\nauthentication/authorization.\n\n## Purpose and Use Cases\n\nPrerequisites are essential for operations that depend on:\n\n1. **Existence Validation**: Ensuring resources exist before manipulation\n2. **State Requirements**: Verifying resources are in the correct state\n3. **Data Dependencies**: Loading necessary data for the current operation\n4. **Business Logic Constraints**: Enforcing domain-specific rules\n\n## Execution Flow\n\nWhen an operation has prerequisites:\n\n1. Each prerequisite API must be called first in the specified order\n2. Prerequisites must return successful responses (2xx status codes)\n3. Only after all prerequisites succeed can the main operation proceed\n4. If any prerequisite fails, the operation should not be attempted\n\n## Common Patterns\n\n### Resource Existence Check\n\n```typescript\n// Before updating an order item, ensure the order exists\nprerequisites: [\n {\n endpoint: { path: \"/orders/{orderId}\", method: \"get\" },\n description: \"Order must exist in the system\",\n },\n];\n```\n\n### State Validation\n\n```typescript\n// Before processing payment, ensure order is in correct state\nprerequisites: [\n {\n endpoint: { path: \"/orders/{orderId}/status\", method: \"get\" },\n description: \"Order must be in 'pending_payment' status\",\n },\n];\n```\n\n### Hierarchical Dependencies\n\n```typescript\n// Before accessing a deeply nested resource\nprerequisites: [\n {\n endpoint: { path: \"/projects/{projectId}\", method: \"get\" },\n description: \"Project must exist\",\n },\n {\n endpoint: {\n path: \"/projects/{projectId}/tasks/{taskId}\",\n method: \"get\",\n },\n description: \"Task must exist within the project\",\n },\n];\n```\n\n## Important Guidelines\n\n1. **Order Matters**: Prerequisites are executed in array order\n2. **Parameter Inheritance**: Path parameters from prerequisites can be used\n in the main operation\n3. **Error Handling**: Failed prerequisites should prevent main operation\n4. **Performance**: Consider caching prerequisite results when appropriate\n5. **Documentation**: Each prerequisite must have a clear description\n explaining why it's required\n6. **No Authentication**: NEVER use prerequisites for authentication checks\n\n## Test Generation Impact\n\nThe Test Agent uses prerequisites to:\n\n- Generate proper test setup sequences\n- Create valid test data in the correct order\n- Ensure test scenarios follow realistic workflows\n- Validate error handling when prerequisites fail"
},
path: {
type: "string",
pattern: "^\\/[a-zA-Z0-9\\/_{}.-]*$",
description: "HTTP path of the API operation.\n\nThe URL path for accessing this API operation, using path parameters\nenclosed in curly braces (e.g., `/shoppings/customers/sales/{saleId}`).\n\nIt must be corresponded to the {@link parameters path parameters}.\n\nThe path structure should clearly indicate which database entity this\noperation is manipulating, helping to ensure all entities have\nappropriate API coverage.\n\nPath validation rules:\n\n- Must start with a forward slash (/)\n- Can contain only: letters (a-z, A-Z), numbers (0-9), forward slashes (/),\n curly braces for parameters ({paramName}), hyphens (-), and underscores\n (_)\n- Parameters must be enclosed in curly braces: {paramName}\n- Resource names should be in camelCase\n- No quotes, spaces, or invalid special characters allowed\n- No domain or role-based prefixes\n\nValid examples:\n\n- \"/users\"\n- \"/users/{userId}\"\n- \"/articles/{articleId}/comments\"\n- \"/attachmentFiles\"\n- \"/orders/{orderId}/items/{itemId}\"\n\nInvalid examples:\n\n- \"'/users'\" (contains quotes)\n- \"/user profile\" (contains space)\n- \"/users/[userId]\" (wrong bracket format)\n- \"/admin/users\" (role prefix)\n- \"/api/v1/users\" (API prefix)"
},
method: {
oneOf: [
{
"const": "get"
},
{
"const": "post"
},
{
"const": "put"
},
{
"const": "delete"
},
{
"const": "patch"
}
],
description: "HTTP method of the API operation.\n\n**IMPORTANT**: Methods must be written in lowercase only (e.g., \"get\",\nnot \"GET\").\n\nNote that, if the API operation has {@link requestBody}, method must not\nbe `get`.\n\nAlso, even though the API operation has been designed to only get\ninformation, but it needs complicated request information, it must be\ndefined as `patch` method with {@link requestBody} data specification.\n\n- `get`: get information\n- `patch`: get information with complicated request data\n ({@link requestBody})\n- `post`: create new record\n- `put`: update existing record\n- `delete`: remove record"
}
},
required: [
"specification",
"authorizationType",
"description",
"summary",
"parameters",
"requestBody",
"responseBody",
"authorizationActor",
"name",
"prerequisites",
"path",
"method"
],
description: "Operation of the Restful API.\n\nThis interface defines a single API endpoint with its HTTP {@link method},\n{@link path}, {@link parameters path parameters},\n{@link requestBody request body}, and {@link responseBody} structure. It\ncorresponds to an individual operation in the paths section of an OpenAPI\ndocument.\n\nEach operation requires a detailed explanation of its purpose through the\nreason and description fields, making it clear why the API was designed and\nhow it should be used.\n\nAll request bodies and responses for this operation must be object types\nand must reference named types defined in the components section. The\ncontent-type is always `application/json`. For file upload/download\noperations, use `string & tags.Format<\"uri\">` in the appropriate schema\ninstead of binary data formats.\n\nIn OpenAPI, this might represent:\n\n```json\n{\n \"/shoppings/customers/orders\": {\n \"post\": {\n \"description\": \"Create a new order application from shopping cart...\",\n \"parameters\": [...],\n \"requestBody\": {...},\n \"responses\": {...},\n ...\n }\n }\n}\n```"
},
"AutoBeOpenApi.IParameter": {
type: "object",
properties: {
name: {
type: "string",
pattern: "^[a-z][a-zA-Z0-9]*$",
description: "Identifier name of the path parameter.\n\nThis name must match exactly with the parameter name in the route path.\nIt must be corresponded to the\n{@link AutoBeOpenApi.IOperation.path API operation path}.\n\nMUST use camelCase naming convention."
},
description: {
type: "string",
description: "Description about the path parameter.\n\nMake short, concise and clear description about the path parameter.\n\n> MUST be written in English. Never use other languages."
},
schema: {
oneOf: [
{
$ref: "#/components/schemas/AutoBeOpenApi.IJsonSchema.INumber"
},
{
$ref: "#/components/schemas/AutoBeOpenApi.IJsonSchema.IInteger"
},
{
$ref: "#/components/schemas/AutoBeOpenApi.IJsonSchema.IString"
}
],
discriminator: {
propertyName: "type",
mapping: {
number: "#/components/schemas/AutoBeOpenApi.IJsonSchema.INumber",
integer: "#/components/schemas/AutoBeOpenApi.IJsonSchema.IInteger",
string: "#/components/schemas/AutoBeOpenApi.IJsonSchema.IString"
}
},
description: "Type schema of the path parameter.\n\nPath parameters are typically primitive types like\n{@link AutoBeOpenApi.IJsonSchema.IString strings},\n{@link AutoBeOpenApi.IJsonSchema.IInteger integers},\n{@link AutoBeOpenApi.IJsonSchema.INumber numbers}.\n\nIf you need other types, please use request body instead with object type\nencapsulation."
}
},
required: [
"name",
"description",
"schema"
],
description: "Path parameter information for API routes.\n\nThis interface defines a path parameter that appears in the URL of an API\nendpoint. Path parameters are enclosed in curly braces in the\n{@link AutoBeOpenApi.IOperation.path operation path} and must be defined\nwith their types and descriptions.\n\nFor example, if API operation path is\n`/shoppings/customers/sales/{saleId}/questions/${questionId}/comments/${commentId}`,\nthe path parameters should be like below:\n\n```json\n{\n \"path\": \"/shoppings/customers/sales/{saleId}/questions/${questionId}/comments/${commentId}\",\n \"method\": \"get\",\n \"parameters\": [\n {\n \"name\": \"saleId\",\n \"in\": \"path\",\n \"schema\": { \"type\": \"string\", \"format\": \"uuid\" },\n \"description\": \"Target sale's ID\"\n },\n {\n \"name\": \"questionId\",\n \"in\": \"path\",\n \"schema\": { \"type\": \"string\", \"format\": \"uuid\" },\n \"description\": \"Target question's ID\"\n },\n {\n \"name\": \"commentId\",\n \"in\": \"path\",\n \"schema\": { \"type\": \"string\", \"format\": \"uuid\" },\n \"description\": \"Target comment's ID\"\n }\n ]\n}\n```"
},
"AutoBeOpenApi.IJsonSchema.INumber": {
type: "object",
properties: {
minimum: {
type: "number",
description: "Minimum value restriction."
},
maximum: {
type: "number",
description: "Maximum value restriction."
},
exclusiveMinimum: {
type: "number",
description: "Exclusive minimum value restriction."
},
exclusiveMaximum: {
type: "number",
description: "Exclusive maximum value restriction."
},
multipleOf: {
type: "number",
exclusiveMinimum: 0,
description: "Multiple of value restriction."
},
type: {
"const": "number",
description: "Discriminator value of the type.\n\nCRITICAL: This MUST be a SINGLE string value, NOT an array. The type\nfield identifies the JSON Schema type and must be exactly one of:\n\"boolean\", \"integer\", \"number\", \"string\", \"array\", \"object\", or\n\"null\".\n\n\u274C INCORRECT: type: [\"string\", \"null\"] // This is WRONG! \u2705 CORRECT:\ntype: \"string\" // For nullable string, use oneOf instead\n\nIf you need to express a nullable type (e.g., string | null), you MUST\nuse the `IOneOf` structure:\n\n```typescript\n{\n \"oneOf\": [{ \"type\": \"string\" }, { \"type\": \"null\" }]\n}\n```\n\nNEVER use array notation in the type field. The type field is a\ndiscriminator that accepts only a single string value."
}
},
required: [
"type"
],
description: "Number (double) type info."
},
"AutoBeOpenApi.IJsonSchema.IInteger": {
type: "object",
properties: {
minimum: {
type: "integer",
description: "Minimum value restriction."
},
maximum: {
type: "integer",
description: "Maximum value restriction."
},
exclusiveMinimum: {
type: "number",
description: "Exclusive minimum value restriction."
},
exclusiveMaximum: {
type: "number",
description: "Exclusive maximum value restriction."
},
multipleOf: {
type: "integer",
exclusiveMinimum: 0,
description: "Multiple of value restriction."
},
type: {
"const": "integer",
description: "Discriminator value of the type.\n\nCRITICAL: This MUST be a SINGLE string value, NOT an array. The type\nfield identifies the JSON Schema type and must be exactly one of:\n\"boolean\", \"integer\", \"number\", \"string\", \"array\", \"object\", or\n\"null\".\n\n\u274C INCORRECT: type: [\"string\", \"null\"] // This is WRONG! \u2705 CORRECT:\ntype: \"string\" // For nullable string, use oneOf instead\n\nIf you need to express a nullable type (e.g., string | null), you MUST\nuse the `IOneOf` structure:\n\n```typescript\n{\n \"oneOf\": [{ \"type\": \"string\" }, { \"type\": \"null\" }]\n}\n```\n\nNEVER use array notation in the type field. The type field is a\ndiscriminator that accepts only a single string value."
}
},
required: [
"type"
],
description: "Integer type info."
},
"AutoBeOpenApi.IJsonSchema.IString": {
type: "object",
properties: {
format: {
oneOf: [
{
"const": "date-time"
},
{
"const": "password"
},
{
"const": "regex"
},
{
"const": "uuid"
},
{
"const": "email"
},
{
"const": "hostname"
},
{
"const": "idn-email"
},
{
"const": "idn-hostname"
},
{
"const": "iri"
},