mirror of
https://github.com/sstent/FitTrack_ReportGenerator.git
synced 2026-01-25 16:41:55 +00:00
sstent
9e0bd322d3
This commit introduces the initial version of the FitTrack Report Generator, a FastAPI application for analyzing workout files. Key features include: - Parsing of FIT, TCX, and GPX workout files. - Analysis of power, heart rate, speed, and elevation data. - Generation of summary reports and charts. - REST API for single and batch workout analysis. The project structure has been set up with a `src` directory for core logic, an `api` directory for the FastAPI application, and a `tests` directory for unit, integration, and contract tests. The development workflow is configured to use Docker and modern Python tooling.
238 lines
7.7 KiB
YAML
238 lines
7.7 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: FitTrack Report Generator API
|
|
version: 1.0.0
|
|
description: API for analyzing workout files and generating reports.
|
|
|
|
servers:
|
|
- url: /api
|
|
description: Base API path
|
|
|
|
paths:
|
|
/analyze/workout:
|
|
post:
|
|
summary: Analyze a single workout file
|
|
description: Uploads a single workout file (FIT, TCX, or GPX) for comprehensive analysis.
|
|
operationId: analyzeSingleWorkout
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
file:
|
|
type: string
|
|
format: binary
|
|
description: The workout file (FIT, TCX, or GPX) to analyze.
|
|
user_id:
|
|
type: string
|
|
format: uuid
|
|
description: Optional user ID to associate the analysis with.
|
|
ftp_value:
|
|
type: number
|
|
format: float
|
|
description: Optional Functional Threshold Power (FTP) value for calculations. Overrides user's default if provided.
|
|
required:
|
|
- file
|
|
responses:
|
|
'200':
|
|
description: Analysis successful. Returns a summary of the analysis.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkoutAnalysisSummary'
|
|
'400':
|
|
description: Invalid input or file format.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'500':
|
|
description: Internal server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
/analyze/batch:
|
|
post:
|
|
summary: Analyze multiple workout files in a batch
|
|
description: Uploads a directory (as a zip file) of workout files for batch analysis and generates a summary report.
|
|
operationId: analyzeBatchWorkouts
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
zip_file:
|
|
type: string
|
|
format: binary
|
|
description: A zip file containing multiple workout files (FIT, TCX, or GPX).
|
|
user_id:
|
|
type: string
|
|
format: uuid
|
|
description: Optional user ID to associate the analysis with.
|
|
ftp_value:
|
|
type: number
|
|
format: float
|
|
description: Optional Functional Threshold Power (FTP) value for calculations. Overrides user's default if provided.
|
|
required:
|
|
- zip_file
|
|
responses:
|
|
'200':
|
|
description: Batch analysis initiated. Returns a summary of the batch process.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
batch_id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique ID for the batch analysis.
|
|
status:
|
|
type: string
|
|
description: Status of the batch analysis (e.g., 'processing', 'completed').
|
|
total_files:
|
|
type: integer
|
|
description: Total number of files submitted in the batch.
|
|
'400':
|
|
description: Invalid input or file format.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'500':
|
|
description: Internal server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
/analysis/{analysis_id}/charts:
|
|
get:
|
|
summary: Retrieve generated charts for a specific analysis
|
|
description: Returns a PNG image of the requested chart for a previously analyzed workout.
|
|
operationId: getAnalysisCharts
|
|
parameters:
|
|
- name: analysis_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
description: The ID of the workout analysis.
|
|
- name: chart_type
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
enum: [power_curve, elevation_profile, zone_distribution_power, zone_distribution_hr, zone_distribution_speed]
|
|
description: The type of chart to retrieve.
|
|
responses:
|
|
'200':
|
|
description: Chart image successfully retrieved.
|
|
content:
|
|
image/png:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'404':
|
|
description: Analysis or chart not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'500':
|
|
description: Internal server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
/analysis/{analysis_id}/summary:
|
|
get:
|
|
summary: Retrieve a summary of a specific analysis
|
|
description: Returns a detailed summary of a previously analyzed workout.
|
|
operationId: getAnalysisSummary
|
|
parameters:
|
|
- name: analysis_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
description: The ID of the workout analysis.
|
|
responses:
|
|
'200':
|
|
description: Analysis summary successfully retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkoutAnalysisSummary'
|
|
'404':
|
|
description: Analysis not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'500':
|
|
description: Internal server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
components:
|
|
schemas:
|
|
WorkoutAnalysisSummary:
|
|
type: object
|
|
properties:
|
|
analysis_id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique ID of the analysis.
|
|
user_id:
|
|
type: string
|
|
format: uuid
|
|
description: User ID associated with the analysis.
|
|
file_name:
|
|
type: string
|
|
description: Original name of the analyzed file.
|
|
analysis_date:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of the analysis.
|
|
status:
|
|
type: string
|
|
description: Status of the analysis (e.g., 'completed', 'failed').
|
|
metrics:
|
|
type: object
|
|
description: Key metrics from the workout analysis (e.g., duration, distance, NP, IF, TSS).
|
|
additionalProperties: true
|
|
report_url:
|
|
type: string
|
|
format: url
|
|
description: URL to the generated report.
|
|
chart_urls:
|
|
type: object
|
|
description: URLs to generated charts.
|
|
additionalProperties:
|
|
type: string
|
|
format: url
|
|
ErrorResponse:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: A unique error code.
|
|
message:
|
|
type: string
|
|
description: A human-readable error message.
|
|
details:
|
|
type: object
|
|
description: Optional additional error details.
|
|
additionalProperties: true |