feagi_api/
openapi.rs

1// Copyright 2025 Neuraville Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4// OpenAPI documentation generation
5//
6// This module generates the OpenAPI 3.0 specification at compile-time
7// using utoipa, ensuring the documentation stays in sync with the code.
8
9use utoipa::openapi::security::{ApiKey, ApiKeyValue, SecurityScheme};
10use utoipa::OpenApi;
11
12use crate::{
13    common::ApiError,
14    v1::{
15        BrainRegionDetail,
16        BrainRegionListResponse,
17        // Brain region DTOs
18        BrainRegionSummary,
19        BurstCountResponse,
20
21        ComponentReadiness,
22
23        ConnectivityStatsResponse,
24        ConnectomeAnalyticsResponse,
25        Coordinates3D,
26        CorticalAreaDetail,
27        CorticalAreaListResponse,
28        CorticalAreaStatsResponse,
29        // Cortical area DTOs
30        CorticalAreaSummary,
31        CreateBrainRegionRequest,
32
33        CreateCorticalAreaRequest,
34        CreateNeuronRequest,
35        Dimensions3D,
36
37        // Genome DTOs
38        GenomeInfoResponse,
39        // Health DTOs
40        HealthCheckResponseV1,
41        LoadGenomeRequest,
42        NeuronCountResponse,
43
44        NeuronDensityResponse,
45        // Neuron DTOs
46        NeuronInfoResponse,
47        NeuronListResponse,
48        PopulatedAreaInfo,
49        PopulatedAreasResponse,
50        ReadinessCheckResponseV1,
51        // Runtime DTOs
52        RuntimeStatusResponse,
53        SaveGenomeRequest,
54        SaveGenomeResponse,
55        SetFrequencyRequest,
56        // Analytics DTOs
57        SystemHealthResponse,
58        UpdateCorticalAreaRequest,
59        ValidateGenomeRequest,
60        ValidateGenomeResponse,
61    },
62};
63
64/// OpenAPI documentation for FEAGI REST API
65#[derive(OpenApi)]
66#[openapi(
67    info(
68        title = "FEAGI REST API",
69        version = "1.0.0",
70        description = "Comprehensive REST API for FEAGI (Foundational Engine for Artificial General Intelligence)",
71        license(
72            name = "Apache-2.0",
73            url = "https://www.apache.org/licenses/LICENSE-2.0"
74        ),
75        contact(
76            name = "FEAGI Team",
77            url = "https://feagi.org",
78            email = "contact@feagi.org"
79        )
80    ),
81    servers(
82        (url = "http://localhost:8000", description = "Default FEAGI server"),
83        (url = "http://localhost:8080", description = "Alternative port")
84    ),
85    paths(
86        // Agent endpoints (registration uses ZMQ/WebSocket only)
87        crate::endpoints::agent::heartbeat,
88        crate::endpoints::agent::list_agents,
89        crate::endpoints::agent::get_agent_properties,
90        crate::endpoints::agent::get_agent_properties_path,
91        crate::endpoints::agent::get_shared_memory,
92        crate::endpoints::agent::deregister_agent,
93        crate::endpoints::agent::manual_stimulation,
94        crate::endpoints::agent::get_fq_sampler_status,
95        crate::endpoints::agent::get_capabilities,
96        crate::endpoints::agent::get_all_agent_capabilities,
97        crate::endpoints::agent::get_agent_info,
98        crate::endpoints::agent::post_configure,
99
100        // System endpoints (21 total)
101        crate::endpoints::system::get_health_check,
102        crate::endpoints::system::get_cortical_area_visualization_skip_rate,
103        crate::endpoints::system::set_cortical_area_visualization_skip_rate,
104        crate::endpoints::system::get_cortical_area_visualization_suppression_threshold,
105        crate::endpoints::system::set_cortical_area_visualization_suppression_threshold,
106        crate::endpoints::system::get_version,
107        crate::endpoints::system::get_versions,
108        crate::endpoints::system::get_configuration,
109        crate::endpoints::system::get_user_preferences,
110        crate::endpoints::system::put_user_preferences,
111        crate::endpoints::system::get_cortical_area_types_list,
112        crate::endpoints::system::post_enable_visualization_fq_sampler,
113        crate::endpoints::system::post_disable_visualization_fq_sampler,
114        crate::endpoints::system::get_fcl_status_system,
115        crate::endpoints::system::post_fcl_reset_system,
116        crate::endpoints::system::get_processes,
117        crate::endpoints::system::get_unique_logs,
118        crate::endpoints::system::get_log_tail,
119        crate::endpoints::system::post_logs,
120        crate::endpoints::system::get_beacon_subscribers,
121        crate::endpoints::system::post_beacon_subscribe,
122        crate::endpoints::system::delete_beacon_unsubscribe,
123        crate::endpoints::system::get_global_activity_visualization,
124        crate::endpoints::system::put_global_activity_visualization,
125        crate::endpoints::system::post_circuit_library_path,
126        crate::endpoints::system::get_influxdb_test,
127        crate::endpoints::system::post_register_system,
128
129        // Cortical Area endpoints
130        crate::endpoints::cortical_area::get_ipu,
131        crate::endpoints::cortical_area::get_ipu_types,
132        crate::endpoints::cortical_area::get_opu,
133        crate::endpoints::cortical_area::get_opu_types,
134        crate::endpoints::cortical_area::get_cortical_area_id_list,
135        crate::endpoints::cortical_area::get_cortical_area_name_list,
136        crate::endpoints::cortical_area::get_cortical_id_name_mapping,
137        crate::endpoints::cortical_area::get_cortical_types,
138        crate::endpoints::cortical_area::get_cortical_map_detailed,
139        crate::endpoints::cortical_area::get_cortical_locations_2d,
140        crate::endpoints::cortical_area::get_cortical_area_geometry,
141        crate::endpoints::cortical_area::get_cortical_visibility,
142        crate::endpoints::cortical_area::post_cortical_name_location,
143        crate::endpoints::cortical_area::post_cortical_area_properties,
144        crate::endpoints::cortical_area::post_multi_cortical_area_properties,
145        crate::endpoints::cortical_area::post_cortical_area,
146        crate::endpoints::cortical_area::put_cortical_area,
147        crate::endpoints::cortical_area::delete_cortical_area,
148        crate::endpoints::cortical_area::post_custom_cortical_area,
149        crate::endpoints::cortical_area::post_clone,
150        crate::endpoints::cortical_area::put_multi_cortical_area,
151        crate::endpoints::cortical_area::delete_multi_cortical_area,
152        crate::endpoints::cortical_area::put_coord_2d,
153        crate::endpoints::cortical_area::put_suppress_cortical_visibility,
154        crate::endpoints::cortical_area::put_reset,
155        crate::endpoints::cortical_area::get_visualization,
156        crate::endpoints::cortical_area::post_batch_operations,
157        crate::endpoints::cortical_area::get_ipu_list,
158        crate::endpoints::cortical_area::get_opu_list,
159        crate::endpoints::cortical_area::put_coordinates_3d,
160        crate::endpoints::cortical_area::delete_bulk,
161        crate::endpoints::cortical_area::post_clone,
162        crate::endpoints::cortical_area::post_resize,
163        crate::endpoints::cortical_area::post_reposition,
164        crate::endpoints::cortical_area::get_voxel_neurons,
165        crate::endpoints::cortical_area::post_voxel_neurons,
166        crate::endpoints::cortical_area::get_memory_cortical_area,
167        crate::endpoints::cortical_area::get_cortical_area_index_list,
168        crate::endpoints::cortical_area::get_cortical_idx_mapping,
169        crate::endpoints::cortical_area::get_mapping_restrictions_query,
170        crate::endpoints::cortical_area::get_memory_usage,
171        crate::endpoints::cortical_area::get_area_neuron_count,
172        crate::endpoints::cortical_area::post_cortical_type_options,
173        crate::endpoints::cortical_area::post_mapping_restrictions,
174        crate::endpoints::cortical_area::post_mapping_restrictions_between_areas,
175        crate::endpoints::cortical_area::put_coord_3d,
176
177        // Morphology endpoints
178        crate::endpoints::morphology::get_morphology_list,
179        crate::endpoints::morphology::get_morphology_types,
180        crate::endpoints::morphology::get_list_types,
181        crate::endpoints::morphology::get_morphologies,
182        crate::endpoints::morphology::post_morphology,
183        crate::endpoints::morphology::put_morphology,
184        crate::endpoints::morphology::put_rename_morphology,
185        crate::endpoints::morphology::delete_morphology_by_name,
186        crate::endpoints::morphology::delete_morphology,  // This is delete_by_id
187        crate::endpoints::morphology::post_morphology_properties,
188        crate::endpoints::morphology::post_morphology_usage,
189        crate::endpoints::morphology::get_list,
190        crate::endpoints::morphology::get_info,
191        crate::endpoints::morphology::post_create,
192        crate::endpoints::morphology::put_update,
193
194        // Genome endpoints (22 total)
195        crate::endpoints::genome::get_file_name,
196        crate::endpoints::genome::get_circuits,
197        crate::endpoints::genome::post_amalgamation_destination,
198        crate::endpoints::genome::delete_amalgamation_cancellation,
199        crate::endpoints::genome::post_genome_append,
200        crate::endpoints::genome::post_upload_barebones_genome,
201        crate::endpoints::genome::post_upload_essential_genome,
202        crate::endpoints::genome::get_name,
203        crate::endpoints::genome::get_timestamp,
204        crate::endpoints::genome::post_save,
205        crate::endpoints::genome::post_load,
206        crate::endpoints::genome::post_upload,
207        crate::endpoints::genome::get_download,
208        crate::endpoints::genome::get_properties,
209        crate::endpoints::genome::post_validate,
210        crate::endpoints::genome::post_transform,
211        crate::endpoints::genome::post_clone,
212        crate::endpoints::genome::post_reset,
213        crate::endpoints::genome::get_metadata,
214        crate::endpoints::genome::post_merge,
215        crate::endpoints::genome::get_diff,
216        crate::endpoints::genome::post_export_format,
217        crate::endpoints::genome::get_amalgamation,
218        crate::endpoints::genome::get_amalgamation_history_exact,
219        crate::endpoints::genome::get_cortical_template,
220        crate::endpoints::genome::get_defaults_files,
221        crate::endpoints::genome::get_download_region,
222        crate::endpoints::genome::get_genome_number,
223        crate::endpoints::genome::post_amalgamation_by_filename,
224        crate::endpoints::genome::post_amalgamation_by_payload,
225        crate::endpoints::genome::post_amalgamation_by_upload,
226        crate::endpoints::genome::post_append_file,
227        crate::endpoints::genome::post_upload_file,
228        crate::endpoints::genome::post_upload_file_edit,
229        crate::endpoints::genome::post_upload_string,
230
231        // Cortical Mapping endpoints (8 total)
232        crate::endpoints::cortical_mapping::post_afferents,
233        crate::endpoints::cortical_mapping::post_efferents,
234        crate::endpoints::cortical_mapping::post_mapping_properties,
235        crate::endpoints::cortical_mapping::put_mapping_properties,
236        crate::endpoints::cortical_mapping::get_mapping,
237        crate::endpoints::cortical_mapping::get_mapping_list,
238        crate::endpoints::cortical_mapping::delete_mapping,
239        crate::endpoints::cortical_mapping::post_batch_update,
240        crate::endpoints::cortical_mapping::post_mapping,
241        crate::endpoints::cortical_mapping::put_mapping,
242
243        // Region endpoints (12 total)
244        crate::endpoints::region::get_regions_members,
245        crate::endpoints::region::post_region,
246        crate::endpoints::region::put_region,
247        crate::endpoints::region::delete_region,
248        crate::endpoints::region::post_clone,
249        crate::endpoints::region::put_relocate_members,
250        crate::endpoints::region::delete_region_and_members,
251        crate::endpoints::region::get_regions,
252        crate::endpoints::region::get_region_titles,
253        crate::endpoints::region::get_region_detail,
254        crate::endpoints::region::put_change_region_parent,
255        crate::endpoints::region::put_change_cortical_area_region,
256
257        // Connectome endpoints (21 total)
258        crate::endpoints::connectome::get_cortical_areas_list_detailed,
259        crate::endpoints::connectome::get_properties_dimensions,
260        crate::endpoints::connectome::get_properties_mappings,
261        crate::endpoints::connectome::get_snapshot,
262        crate::endpoints::connectome::get_stats,
263        crate::endpoints::connectome::post_batch_neuron_operations,
264        crate::endpoints::connectome::post_batch_synapse_operations,
265        crate::endpoints::connectome::get_neuron_count,
266        crate::endpoints::connectome::get_synapse_count,
267        crate::endpoints::connectome::get_paths,
268        crate::endpoints::connectome::get_cumulative_stats,
269        crate::endpoints::connectome::get_area_details,
270        crate::endpoints::connectome::post_rebuild,
271        crate::endpoints::connectome::get_structure,
272        crate::endpoints::connectome::post_clear,
273        crate::endpoints::connectome::get_validation,
274        crate::endpoints::connectome::get_topology,
275        crate::endpoints::connectome::post_optimize,
276        crate::endpoints::connectome::get_connectivity_matrix,
277        crate::endpoints::connectome::post_neurons_batch,
278        crate::endpoints::connectome::post_synapses_batch,
279        crate::endpoints::connectome::get_cortical_areas_list_summary,
280        crate::endpoints::connectome::get_cortical_areas_list_transforming,
281        crate::endpoints::connectome::get_cortical_area_list_types,
282        crate::endpoints::connectome::get_cortical_area_neurons,
283        crate::endpoints::connectome::get_area_synapses,
284        crate::endpoints::connectome::get_area_synapses_incoming,
285        crate::endpoints::connectome::get_cortical_info,
286        crate::endpoints::connectome::get_stats_cortical_cumulative,
287        crate::endpoints::connectome::get_neuron_properties_by_id,
288        crate::endpoints::connectome::get_neuron_properties_query,
289        crate::endpoints::connectome::get_neuron_properties_at_query,
290        crate::endpoints::connectome::get_memory_neuron,
291        crate::endpoints::connectome::get_area_neurons_query,
292        crate::endpoints::connectome::get_fire_queue_area,
293        crate::endpoints::connectome::get_plasticity_info,
294        crate::endpoints::connectome::get_path_query,
295        crate::endpoints::connectome::get_download_connectome,
296        crate::endpoints::connectome::get_download_cortical_area,
297        crate::endpoints::connectome::post_upload_connectome,
298        crate::endpoints::connectome::post_upload_cortical_area,
299
300        // Burst Engine endpoints (14 total)
301        crate::endpoints::burst_engine::get_simulation_timestep,
302        crate::endpoints::burst_engine::post_simulation_timestep,
303        crate::endpoints::burst_engine::get_fcl,
304        crate::endpoints::burst_engine::get_fcl_neuron,
305        crate::endpoints::burst_engine::get_fire_queue,
306        crate::endpoints::burst_engine::get_fire_queue_neuron,
307        crate::endpoints::burst_engine::post_fcl_reset,
308        crate::endpoints::burst_engine::get_fcl_status,
309        crate::endpoints::burst_engine::get_fcl_sampler_config,
310        crate::endpoints::burst_engine::post_fcl_sampler_config,
311        crate::endpoints::burst_engine::get_area_fcl_sample_rate,
312        crate::endpoints::burst_engine::post_area_fcl_sample_rate,
313        crate::endpoints::burst_engine::get_fire_ledger_default_window_size,
314        crate::endpoints::burst_engine::put_fire_ledger_default_window_size,
315        crate::endpoints::burst_engine::get_fire_ledger_areas_window_config,
316        crate::endpoints::burst_engine::get_stats,
317        crate::endpoints::burst_engine::get_status,
318        crate::endpoints::burst_engine::post_control,
319        crate::endpoints::burst_engine::get_burst_counter,
320        crate::endpoints::burst_engine::post_start,
321        crate::endpoints::burst_engine::post_stop,
322        crate::endpoints::burst_engine::post_hold,
323        crate::endpoints::burst_engine::post_resume,
324        crate::endpoints::burst_engine::get_config,
325        crate::endpoints::burst_engine::put_config,
326        crate::endpoints::burst_engine::get_fire_ledger_area_window_size,
327        crate::endpoints::burst_engine::put_fire_ledger_area_window_size,
328        crate::endpoints::burst_engine::get_fire_ledger_history,
329        crate::endpoints::burst_engine::get_membrane_potentials,
330        crate::endpoints::burst_engine::put_membrane_potentials,
331        crate::endpoints::burst_engine::get_frequency_status,
332        crate::endpoints::burst_engine::post_measure_frequency,
333        crate::endpoints::burst_engine::get_frequency_history,
334        crate::endpoints::burst_engine::post_force_connectome_integration,
335
336        // Insight endpoints
337        crate::endpoints::insight::post_neurons_membrane_potential_status,
338        crate::endpoints::insight::post_neuron_synaptic_potential_status,
339        crate::endpoints::insight::post_neurons_membrane_potential_set,
340        crate::endpoints::insight::post_neuron_synaptic_potential_set,
341
342        // Neuroplasticity endpoints (7 total)
343        crate::endpoints::neuroplasticity::get_plasticity_queue_depth,
344        crate::endpoints::neuroplasticity::put_plasticity_queue_depth,
345        crate::endpoints::neuroplasticity::get_status,
346        crate::endpoints::neuroplasticity::get_transforming,
347        crate::endpoints::neuroplasticity::post_configure,
348        crate::endpoints::neuroplasticity::post_enable_area,
349        crate::endpoints::neuroplasticity::post_disable_area,
350
351        // Input endpoints
352        crate::endpoints::input::get_vision,
353        crate::endpoints::input::post_vision,
354        crate::endpoints::input::get_sensor_snapshot_last,
355
356        // Outputs endpoints
357        crate::endpoints::outputs::get_targets,
358        crate::endpoints::outputs::post_configure,
359        crate::endpoints::outputs::get_motor_snapshot_last,
360
361        // Physiology endpoints
362        crate::endpoints::physiology::get_physiology,
363        crate::endpoints::physiology::put_physiology,
364
365        // Simulation endpoints
366        crate::endpoints::simulation::post_stimulation_upload,
367        crate::endpoints::simulation::post_reset,
368        crate::endpoints::simulation::get_status,
369        crate::endpoints::simulation::get_stats,
370        crate::endpoints::simulation::post_config,
371
372        // Training endpoints
373        crate::endpoints::training::post_shock,
374        crate::endpoints::training::get_shock_options,
375        crate::endpoints::training::get_shock_status,
376        crate::endpoints::training::post_reward_intensity,
377        crate::endpoints::training::post_punishment_intensity,
378        crate::endpoints::training::post_gameover,
379        crate::endpoints::training::get_brain_fitness,
380        crate::endpoints::training::get_fitness_criteria,
381        crate::endpoints::training::put_fitness_criteria,
382        crate::endpoints::training::get_fitness_stats,
383        crate::endpoints::training::get_training_report,
384        crate::endpoints::training::get_status,
385        crate::endpoints::training::get_stats,
386        crate::endpoints::training::post_config,
387
388        // Visualization endpoints
389        crate::endpoints::visualization::post_register_client,
390        crate::endpoints::visualization::post_unregister_client,
391        crate::endpoints::visualization::post_heartbeat,
392        crate::endpoints::visualization::get_status,
393
394        // Monitoring endpoints
395        crate::endpoints::monitoring::get_status,
396        crate::endpoints::monitoring::get_metrics,
397        crate::endpoints::monitoring::get_data,
398
399        // Evolution endpoints
400        crate::endpoints::evolution::get_status,
401        crate::endpoints::evolution::post_config,
402
403        // Snapshot endpoints
404        // TODO: Implement snapshot endpoints
405        // crate::endpoints::snapshot::post_create,
406        // crate::endpoints::snapshot::post_restore,
407        // crate::endpoints::snapshot::get_list,
408        // crate::endpoints::snapshot::delete_snapshot,
409        // crate::endpoints::snapshot::get_artifact,
410        // crate::endpoints::snapshot::post_compare,
411        // crate::endpoints::snapshot::post_upload,
412
413        // Network endpoints
414        crate::endpoints::network::get_status,
415        crate::endpoints::network::post_config,
416        crate::endpoints::network::get_connection_info,
417    ),
418    components(
419        schemas(
420            // Common
421            ApiError,
422
423            // Health
424            HealthCheckResponseV1,
425            ReadinessCheckResponseV1,
426            ComponentReadiness,
427
428            // Agent
429            crate::v1::AgentRegistrationRequest,
430
431            // Outputs
432            crate::v1::OutputTargetsResponse,
433            crate::v1::OutputConfigRequest,
434            crate::v1::OutputConfigResponse,
435            crate::endpoints::outputs::MotorSnapshotResponse,
436            crate::endpoints::outputs::MotorTapArea,
437            crate::endpoints::outputs::MotorTapSample,
438            crate::endpoints::outputs::MotorTapAgent,
439
440            // Input
441            crate::endpoints::input::SensorSnapshotResponse,
442            crate::endpoints::input::SensorTapArea,
443            crate::endpoints::input::SensorTapSample,
444
445            // Physiology
446            crate::v1::PhysiologyResponse,
447            crate::v1::PhysiologyParameters,
448            crate::v1::PhysiologyUpdateRequest,
449            crate::v1::PhysiologyUpdateResponse,
450
451            // Burst Engine
452            crate::v1::FCLResponse,
453            crate::v1::FireQueueResponse,
454            crate::v1::FCLStatusResponse,
455            crate::v1::FireLedgerConfigResponse,
456            crate::v1::BurstEngineStats,
457            crate::v1::BurstEngineStatus,
458            crate::v1::BurstEngineControlRequest,
459
460            // Monitoring
461            crate::v1::MonitoringStatusResponse,
462            crate::v1::SystemMetricsResponse,
463            crate::v1::MonitoringData,
464            crate::v1::MonitoringDataResponse,
465
466            // Simulation
467            crate::v1::StimulationUploadRequest,
468            crate::v1::SimulationControlRequest,
469            crate::v1::SimulationStatusResponse,
470            crate::v1::SimulationStatsResponse,
471            crate::v1::SimulationSuccessResponse,
472
473            // Training
474            crate::v1::ShockConfigRequest,
475            crate::v1::ShockOptionsResponse,
476            crate::v1::ShockStatusResponse,
477            crate::v1::IntensityRequest,
478            crate::v1::BrainFitnessResponse,
479            crate::v1::FitnessCriteriaResponse,
480            crate::v1::FitnessCriteriaUpdateRequest,
481            crate::v1::FitnessStatsResponse,
482            crate::v1::TrainingReportResponse,
483            crate::v1::TrainingStatusResponse,
484            crate::v1::TrainingStatsResponse,
485            crate::v1::TrainingConfigRequest,
486            crate::v1::TrainingSuccessResponse,
487
488            // Visualization
489            crate::v1::VisualizationClientRequest,
490            crate::v1::VisualizationClientResponse,
491            crate::v1::VisualizationHeartbeatRequest,
492            crate::v1::VisualizationStatusResponse,
493            crate::v1::VisualizationSuccessResponse,
494
495            // Evolution
496            crate::v1::EvolutionStatusResponse,
497            crate::v1::EvolutionConfigRequest,
498            crate::v1::EvolutionSuccessResponse,
499
500            // Snapshot
501            crate::v1::SnapshotCreateRequest,
502            crate::v1::SnapshotCreateResponse,
503            crate::v1::SnapshotRestoreRequest,
504            crate::v1::SnapshotListResponse,
505            crate::v1::SnapshotInfo,
506            crate::v1::SnapshotArtifactResponse,
507            crate::v1::SnapshotCompareRequest,
508            crate::v1::SnapshotCompareResponse,
509            crate::v1::SnapshotUploadRequest,
510            crate::v1::SnapshotUploadResponse,
511            crate::v1::SnapshotSuccessResponse,
512
513            // Network
514            crate::v1::NetworkStatusResponse,
515            crate::v1::NetworkConnectionInfo,
516            crate::v1::ConnectionInfoApi,
517            crate::v1::ConnectionInfoZmq,
518            crate::v1::ConnectionInfoZmqPorts,
519            crate::v1::ConnectionInfoZmqEndpoints,
520            crate::v1::ConnectionInfoWebSocket,
521            crate::v1::ConnectionInfoWebSocketPorts,
522            crate::v1::ConnectionInfoWebSocketEndpoints,
523            crate::v1::ConnectionInfoShm,
524            crate::v1::ConnectionInfoUdp,
525            crate::v1::ConnectionInfoBluetooth,
526            crate::v1::ConnectionInfoStreamStatus,
527            crate::v1::NetworkConfigRequest,
528            crate::v1::NetworkSuccessResponse,
529            crate::v1::AgentRegistrationResponse,
530            crate::v1::HeartbeatRequest,
531            crate::v1::HeartbeatResponse,
532            crate::v1::AgentListResponse,
533            crate::v1::AgentPropertiesResponse,
534            crate::v1::AgentCapabilitiesSummary,
535            crate::v1::AgentDeregistrationRequest,
536            crate::v1::SuccessResponse,
537            crate::v1::ManualStimulationRequest,
538            crate::v1::ManualStimulationResponse,
539            crate::v1::DeviceRegistrationExportResponse,
540            crate::v1::DeviceRegistrationImportRequest,
541            crate::v1::DeviceRegistrationImportResponse,
542
543            // System
544            crate::endpoints::system::HealthCheckResponse,
545            crate::endpoints::system::LogTailResponse,
546            crate::endpoints::system::LogTailRecord,
547
548            // Cortical Area
549            crate::endpoints::cortical_area::CorticalAreaIdListResponse,
550            crate::endpoints::cortical_area::CorticalAreaNameListResponse,
551            crate::endpoints::cortical_area::CorticalAreaResetRequest,
552            crate::endpoints::cortical_area::CorticalAreaResetResponse,
553            crate::endpoints::cortical_area::CorticalAreaResetItem,
554            crate::endpoints::cortical_area::CorticalTypeMetadata,
555            crate::endpoints::cortical_area::VoxelNeuronsQuery,
556            crate::endpoints::cortical_area::VoxelNeuronsBody,
557            crate::endpoints::cortical_area::VoxelNeuronsResponse,
558            crate::endpoints::cortical_area::MemoryCorticalAreaQuery,
559            crate::endpoints::cortical_area::MemoryCorticalAreaParamsResponse,
560            crate::endpoints::cortical_area::MemoryCorticalAreaResponse,
561            crate::endpoints::connectome::MemoryNeuronQuery,
562            crate::endpoints::connectome::MemoryNeuronDetailResponse,
563
564            // Morphology
565            crate::endpoints::morphology::MorphologyListResponse,
566            crate::endpoints::morphology::RenameMorphologyRequest,
567
568            // Cortical Areas
569            CorticalAreaSummary,
570            CorticalAreaDetail,
571            CorticalAreaListResponse,
572            CreateCorticalAreaRequest,
573            UpdateCorticalAreaRequest,
574            Coordinates3D,
575            Dimensions3D,
576
577            // Brain Regions
578            BrainRegionSummary,
579            BrainRegionDetail,
580            BrainRegionListResponse,
581            CreateBrainRegionRequest,
582
583            // Genome
584            GenomeInfoResponse,
585            LoadGenomeRequest,
586            SaveGenomeRequest,
587            SaveGenomeResponse,
588            ValidateGenomeRequest,
589            ValidateGenomeResponse,
590            crate::endpoints::genome::GenomeFileUploadForm,
591
592            // Neurons
593            NeuronInfoResponse,
594            CreateNeuronRequest,
595            NeuronListResponse,
596            NeuronCountResponse,
597
598            // Runtime
599            RuntimeStatusResponse,
600            SetFrequencyRequest,
601            BurstCountResponse,
602
603            // Analytics
604            SystemHealthResponse,
605            CorticalAreaStatsResponse,
606            ConnectivityStatsResponse,
607            ConnectomeAnalyticsResponse,
608            PopulatedAreasResponse,
609            PopulatedAreaInfo,
610            NeuronDensityResponse,
611        )
612    ),
613    tags(
614        (name = "agent", description = "Agent registration and heartbeat"),
615        (name = "system", description = "System health and configuration"),
616        (name = "cortical_area", description = "Cortical area management"),
617        (name = "morphology", description = "Morphology management"),
618        (name = "genome", description = "Genome operations"),
619        (name = "cortical_mapping", description = "Cortical mapping operations"),
620        (name = "region", description = "Brain region management"),
621        (name = "connectome", description = "Connectome operations"),
622        (name = "burst_engine", description = "Burst engine configuration and FCL/Fire Queue"),
623        (name = "insight", description = "Neuron insight operations"),
624        (name = "neuroplasticity", description = "Neuroplasticity configuration"),
625        (name = "input", description = "Input operations"),
626        (name = "outputs", description = "Output/motor target management"),
627        (name = "physiology", description = "Physiology parameter configuration"),
628        (name = "simulation", description = "Simulation control and stimulation"),
629        (name = "training", description = "Reinforcement learning and training"),
630        (name = "visualization", description = "Visualization client management"),
631        (name = "monitoring", description = "System monitoring and metrics"),
632        (name = "evolution", description = "Evolutionary algorithms"),
633        (name = "snapshot", description = "Brain snapshot management"),
634        (name = "network", description = "Network configuration"),
635    ),
636    modifiers(&SecurityAddon)
637)]
638pub struct ApiDoc;
639
640/// Security scheme configuration
641struct SecurityAddon;
642
643impl utoipa::Modify for SecurityAddon {
644    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
645        if let Some(components) = openapi.components.as_mut() {
646            // API Key authentication (for future use)
647            components.add_security_scheme(
648                "api_key",
649                SecurityScheme::ApiKey(ApiKey::Header(ApiKeyValue::new("X-API-Key"))),
650            );
651
652            // JWT Bearer authentication (for future use)
653            components.add_security_scheme(
654                "bearer_auth",
655                SecurityScheme::Http(
656                    utoipa::openapi::security::HttpBuilder::new()
657                        .scheme(utoipa::openapi::security::HttpAuthScheme::Bearer)
658                        .bearer_format("JWT")
659                        .build(),
660                ),
661            );
662        }
663    }
664}
665
666/// Get OpenAPI JSON specification
667pub fn get_openapi_json() -> String {
668    ApiDoc::openapi()
669        .to_pretty_json()
670        .unwrap_or_else(|e| format!(r#"{{"error": "Failed to generate OpenAPI spec: {}"}}"#, e))
671}
672
673/// Get OpenAPI YAML specification
674pub fn get_openapi_yaml() -> String {
675    // utoipa supports YAML output, but we need to implement it
676    // For now, return a notice
677    "# OpenAPI YAML generation not yet implemented\n# Use /openapi.json instead".to_string()
678}
679
680#[cfg(test)]
681mod tests {
682    use super::*;
683
684    #[test]
685    fn test_openapi_generation() {
686        let json = get_openapi_json();
687        assert!(json.contains("FEAGI REST API"));
688        assert!(json.contains("health"));
689        assert!(json.contains("ready"));
690    }
691
692    #[test]
693    fn test_openapi_components() {
694        let openapi = ApiDoc::openapi();
695        assert!(openapi.components.is_some());
696
697        let components = openapi.components.unwrap();
698        assert!(components.schemas.contains_key("HealthCheckResponseV1"));
699        assert!(components.schemas.contains_key("ApiError"));
700        assert!(components.schemas.contains_key("VoxelNeuronsBody"));
701        assert!(components.schemas.contains_key("VoxelNeuronsResponse"));
702        assert!(components.schemas.contains_key("VoxelNeuronsQuery"));
703        assert!(components
704            .schemas
705            .contains_key("MemoryCorticalAreaResponse"));
706        assert!(components
707            .schemas
708            .contains_key("MemoryNeuronDetailResponse"));
709    }
710
711    #[test]
712    fn test_openapi_amalgamation_by_upload_is_multipart_form() {
713        let openapi = ApiDoc::openapi();
714        let json = serde_json::to_value(&openapi).expect("serialize openapi");
715
716        let content =
717            &json["paths"]["/v1/genome/amalgamation_by_upload"]["post"]["requestBody"]["content"];
718
719        assert!(
720            content.get("multipart/form-data").is_some(),
721            "Expected multipart/form-data content for /v1/genome/amalgamation_by_upload requestBody. Got: {}",
722            content
723        );
724    }
725
726    #[test]
727    fn test_security_schemes() {
728        let openapi = ApiDoc::openapi();
729        let components = openapi.components.unwrap();
730
731        assert!(components.security_schemes.contains_key("api_key"));
732        assert!(components.security_schemes.contains_key("bearer_auth"));
733    }
734}
feagi_api/openapi.rs

feagi_api/
openapi.rs
