Router
Description
Defines API endpoints (e.g., using FastAPI) and maps HTTP requests to Application layer services (Commands/Queries).
Definition Schema
The definition for a router component expects the following structure:
{
"$defs": {
"BodyParamMetadata": {
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Title"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Description"
},
"deprecated": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Deprecated"
},
"source_marker": {
"const": "body",
"default": "body",
"title": "Source Marker",
"type": "string"
},
"embed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": false,
"title": "Embed"
},
"media_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "application/json",
"title": "Media Type"
},
"alias": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Alias"
},
"examples": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Examples"
}
},
"title": "BodyParamMetadata",
"type": "object"
},
"CookieParamMetadata": {
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Title"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Description"
},
"deprecated": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Deprecated"
},
"source_marker": {
"const": "cookie",
"default": "cookie",
"title": "Source Marker",
"type": "string"
},
"alias": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Alias"
}
},
"title": "CookieParamMetadata",
"type": "object"
},
"DependencyParamMetadata": {
"properties": {
"source_marker": {
"const": "dependency",
"default": "dependency",
"title": "Source Marker",
"type": "string"
},
"dependency_callable_str": {
"title": "Dependency Callable Str",
"type": "string"
},
"use_cache": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Use Cache"
}
},
"required": [
"dependency_callable_str"
],
"title": "DependencyParamMetadata",
"type": "object"
},
"HeaderParamMetadata": {
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Title"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Description"
},
"deprecated": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Deprecated"
},
"source_marker": {
"const": "header",
"default": "header",
"title": "Source Marker",
"type": "string"
},
"alias": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Alias"
},
"convert_underscores": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Convert Underscores"
}
},
"title": "HeaderParamMetadata",
"type": "object"
},
"HttpMethod": {
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE",
"HEAD",
"OPTIONS",
"TRACE"
],
"title": "HttpMethod",
"type": "string"
},
"ParamSource": {
"enum": [
"path",
"query",
"header",
"cookie",
"body",
"dependency",
"background_tasks",
"request",
"response"
],
"title": "ParamSource",
"type": "string"
},
"PathParamMetadata": {
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Title"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Description"
},
"deprecated": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Deprecated"
},
"source_marker": {
"const": "path",
"default": "path",
"title": "Source Marker",
"type": "string"
},
"ge": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Ge"
},
"gt": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Gt"
},
"le": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Le"
},
"lt": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Lt"
},
"min_length": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Length"
},
"max_length": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Length"
},
"regex": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Regex"
}
},
"title": "PathParamMetadata",
"type": "object"
},
"QueryParamMetadata": {
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Title"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Description"
},
"deprecated": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Deprecated"
},
"source_marker": {
"const": "query",
"default": "query",
"title": "Source Marker",
"type": "string"
},
"ge": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Ge"
},
"gt": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Gt"
},
"le": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Le"
},
"lt": {
"anyOf": [
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Lt"
},
"min_length": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Length"
},
"max_length": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Length"
},
"regex": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Regex"
},
"alias": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Alias"
}
},
"title": "QueryParamMetadata",
"type": "object"
},
"RouteInputDTO": {
"example": {
"dependencies_str": [
"dependencies.verify_api_key"
],
"function_name": "update_item_generated",
"method": "PUT",
"parameters": [
{
"metadata": {
"ge": 1,
"source_marker": "path"
},
"param_name": "item_id",
"param_type_str": "int",
"source": "path"
},
{
"default_value_str": "False",
"metadata": {
"alias": "notify-user",
"source_marker": "query"
},
"param_name": "notify",
"param_type_str": "bool",
"source": "query"
},
{
"metadata": {
"embed": true,
"source_marker": "body"
},
"param_name": "item_data",
"param_type_str": "schemas.ItemUpdate",
"source": "body"
},
{
"metadata": {
"dependency_callable_str": "dependencies.get_db",
"source_marker": "dependency"
},
"param_name": "db",
"param_type_str": "Session",
"source": "dependency"
},
{
"metadata": {
"source_marker": "background_tasks"
},
"param_name": "bg_tasks",
"param_type_str": "BackgroundTasks",
"source": "background_tasks"
}
],
"path": "/{item_id}",
"response_model_str": "schemas.ItemResponse",
"status_code": 200,
"summary": "Update an Item",
"tags": [
"Items",
"CRUD"
]
},
"properties": {
"path": {
"title": "Path",
"type": "string"
},
"method": {
"$ref": "#/$defs/HttpMethod"
},
"function_name": {
"title": "Function Name",
"type": "string"
},
"response_model_str": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Response Model Str"
},
"status_code": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Status Code"
},
"summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Summary"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Description"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Tags"
},
"dependencies_str": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Dependencies Str"
},
"responses": {
"anyOf": [
{
"additionalProperties": {
"additionalProperties": true,
"type": "object"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Responses"
},
"deprecated": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Deprecated"
},
"include_in_schema": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": true,
"title": "Include In Schema"
},
"operation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Operation Id"
},
"response_description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "Successful Response",
"title": "Response Description"
},
"response_class_str": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Response Class Str"
},
"parameters": {
"items": {
"$ref": "#/$defs/RouteParameterInputDTO"
},
"title": "Parameters",
"type": "array"
}
},
"required": [
"path",
"method",
"function_name"
],
"title": "RouteInputDTO",
"type": "object"
},
"RouteParameterInputDTO": {
"example": {
"default_value_str": null,
"metadata": {
"description": "The unique identifier for the item.",
"ge": 1,
"source_marker": "path",
"title": "Item ID"
},
"param_name": "item_id",
"param_type_str": "int",
"source": "path"
},
"properties": {
"param_name": {
"title": "Param Name",
"type": "string"
},
"param_type_str": {
"title": "Param Type Str",
"type": "string"
},
"source": {
"$ref": "#/$defs/ParamSource"
},
"default_value_str": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Default Value Str"
},
"metadata": {
"anyOf": [
{
"$ref": "#/$defs/PathParamMetadata"
},
{
"$ref": "#/$defs/QueryParamMetadata"
},
{
"$ref": "#/$defs/HeaderParamMetadata"
},
{
"$ref": "#/$defs/CookieParamMetadata"
},
{
"$ref": "#/$defs/BodyParamMetadata"
},
{
"$ref": "#/$defs/DependencyParamMetadata"
},
{
"$ref": "#/$defs/UtilityParamMetadata"
},
{
"type": "null"
}
],
"default": null,
"title": "Metadata"
}
},
"required": [
"param_name",
"param_type_str",
"source"
],
"title": "RouteParameterInputDTO",
"type": "object"
},
"UtilityParamMetadata": {
"properties": {
"source_marker": {
"enum": [
"request",
"response",
"background_tasks"
],
"title": "Source Marker",
"type": "string"
}
},
"required": [
"source_marker"
],
"title": "UtilityParamMetadata",
"type": "object"
}
},
"example": {
"dependencies_str": [
"dependencies.verify_global_token"
],
"prefix": "/api/v1/items",
"router_variable_name": "items_router",
"routes": [],
"tags": [
"Items API"
]
},
"properties": {
"name": {
"description": "The logical name or filename for the router, matching the operation name.",
"title": "Name",
"type": "string"
},
"router_variable_name": {
"default": "router",
"title": "Router Variable Name",
"type": "string"
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Prefix"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Tags"
},
"dependencies_str": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Dependencies Str"
},
"responses": {
"anyOf": [
{
"additionalProperties": {
"additionalProperties": true,
"type": "object"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"title": "Responses"
},
"routes": {
"items": {
"$ref": "#/$defs/RouteInputDTO"
},
"title": "Routes",
"type": "array"
}
},
"required": [
"name",
"routes"
],
"title": "RouterInputDTO",
"type": "object"
}
Naming and Location Conventions
Class: PascalCase, typically ends with 'Router'. File: ${router_name}.py (based on ${router_name}). Location: app/api/${version}/routers. (Requires context: ['version'])
Example Definition
{
"router_variable_name": "items_router",
"prefix": "/api/v1/items",
"tags": [
"Items API"
],
"dependencies_str": [
"dependencies.verify_global_token"
],
"routes": []
}