docs: comprehensive documentation overhaul
Add complete documentation structure: - Frontend architecture documentation - Database schema documentation - Deployment guides (Docker, Traefik, Authentik, Environment) - Development guides (Setup, Testing, Contributing, Quality Gates) - Deployment architecture documentation - Updated docs README with complete navigation All new features and APIs are now documented. Quality gates: docs only, no code changes
This commit is contained in:
Fusion
@@ -0,0 +1,349 @@
|
||||
# Repositories API
|
||||
|
||||
Git repository and file management endpoints.
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require authentication (session cookie).
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories
|
||||
|
||||
**Description:** List repositories in a project.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "my-repo",
|
||||
"clone_url": "https://github.com/user/repo.git",
|
||||
"is_mirror": true,
|
||||
"project_id": "uuid",
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /projects/{project_id}/repositories
|
||||
|
||||
**Description:** Create a new repository.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-repo",
|
||||
"remote_url": "https://github.com/user/repo.git",
|
||||
"is_mirror": false
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | `string` | Yes | Repository name |
|
||||
| `remote_url` | `string` | No | Remote URL to clone from |
|
||||
| `is_mirror` | `boolean` | No | Create mirror clone (default: false) |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (201 Created)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "my-repo",
|
||||
"clone_url": "https://github.com/user/repo.git",
|
||||
"is_mirror": false,
|
||||
"project_id": "uuid",
|
||||
"created_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
#### URL Parsing Suggestion (422 Unprocessable Entity)
|
||||
|
||||
If the URL appears to be a browser URL:
|
||||
|
||||
```json
|
||||
{
|
||||
"detail": "URL appears to be a browser URL, not a git clone URL",
|
||||
"suggested_url": "https://github.com/user/repo.git",
|
||||
"original_url": "https://github.com/user/repo/tree/main",
|
||||
"error_code": "URL_NEEDS_PARSING"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DELETE /projects/{project_id}/repositories/{id}
|
||||
|
||||
**Description:** Delete a repository.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (204 No Content)
|
||||
|
||||
**Warning:** Permanently deletes the repository from disk. Cannot be undone.
|
||||
|
||||
---
|
||||
|
||||
## POST /projects/{project_id}/repositories/parse-url
|
||||
|
||||
**Description:** Parse and validate a git URL.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://github.com/user/repo/tree/main"
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"original_url": "https://github.com/user/repo/tree/main",
|
||||
"base_url": "https://github.com/user/repo.git",
|
||||
"is_valid_clone_url": false,
|
||||
"needs_parsing": true,
|
||||
"host": "github.com",
|
||||
"message": "This URL contains a branch path. The repository URL is: https://github.com/user/repo.git"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories/{id}/files
|
||||
|
||||
**Description:** List files in a directory.
|
||||
|
||||
### Request
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `branch` | `string` | No | Branch name (default: repository default) |
|
||||
| `path` | `string` | No | Directory path (default: root) |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src",
|
||||
"branch": "main",
|
||||
"entries": [
|
||||
{
|
||||
"name": "components",
|
||||
"type": "directory",
|
||||
"path": "src/components"
|
||||
},
|
||||
{
|
||||
"name": "main.py",
|
||||
"type": "file",
|
||||
"path": "src/main.py",
|
||||
"size": 1234,
|
||||
"last_commit": {
|
||||
"hash": "abc123",
|
||||
"message": "Initial commit",
|
||||
"author": "John Doe",
|
||||
"date": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories/{id}/files/content
|
||||
|
||||
**Description:** Get file content.
|
||||
|
||||
### Request
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `branch` | `string` | Yes | Branch name |
|
||||
| `path` | `string` | Yes | File path |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/main.py",
|
||||
"branch": "main",
|
||||
"content": "function hello() {\n return 'world';\n}",
|
||||
"size": 42,
|
||||
"encoding": "utf-8",
|
||||
"language": "python",
|
||||
"is_binary": false
|
||||
}
|
||||
```
|
||||
|
||||
#### Binary File (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "image.png",
|
||||
"branch": "main",
|
||||
"content": null,
|
||||
"size": 12345,
|
||||
"encoding": null,
|
||||
"language": null,
|
||||
"is_binary": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /projects/{project_id}/repositories/{id}/files/content
|
||||
|
||||
**Description:** Update file content and commit.
|
||||
|
||||
### Request
|
||||
|
||||
#### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/main.py",
|
||||
"branch": "main",
|
||||
"content": "new content",
|
||||
"commit_message": "Update file",
|
||||
"author_name": "User",
|
||||
"author_email": "user@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `path` | `string` | Yes | File path |
|
||||
| `branch` | `string` | Yes | Branch name |
|
||||
| `content` | `string` | Yes | New file content |
|
||||
| `commit_message` | `string` | Yes | Commit message |
|
||||
| `author_name` | `string` | Yes | Author name |
|
||||
| `author_email` | `string` | Yes | Author email |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"commit_hash": "def789",
|
||||
"message": "Update file",
|
||||
"branch": "main"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories/{id}/branches
|
||||
|
||||
**Description:** List branches.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"branches": [
|
||||
{
|
||||
"name": "main",
|
||||
"is_default": true,
|
||||
"last_commit": {
|
||||
"hash": "abc123",
|
||||
"message": "Initial commit",
|
||||
"date": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
}
|
||||
],
|
||||
"default_branch": "main"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories/{id}/history
|
||||
|
||||
**Description:** Get commit history.
|
||||
|
||||
### Request
|
||||
|
||||
#### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `branch` | `string` | No | Branch name (default: all branches) |
|
||||
| `max_count` | `integer` | No | Maximum commits to return (default: 1000) |
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"commits": [
|
||||
{
|
||||
"hash": "abc123",
|
||||
"author_name": "John Doe",
|
||||
"author_email": "john@example.com",
|
||||
"author_date": "2024-01-01T00:00:00Z",
|
||||
"message": "Initial commit",
|
||||
"refs": ["HEAD", "main"]
|
||||
}
|
||||
],
|
||||
"branch": "main",
|
||||
"total_count": 50
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /projects/{project_id}/repositories/{id}/commits/{hash}
|
||||
|
||||
**Description:** Get commit details.
|
||||
|
||||
### Response
|
||||
|
||||
#### Success (200 OK)
|
||||
|
||||
```json
|
||||
{
|
||||
"hash": "abc123",
|
||||
"author_name": "John Doe",
|
||||
"author_email": "john@example.com",
|
||||
"author_date": "2024-01-01T00:00:00Z",
|
||||
"committer_name": "John Doe",
|
||||
"committer_email": "john@example.com",
|
||||
"commit_date": "2024-01-01T00:00:00Z",
|
||||
"message": "Initial commit",
|
||||
"stats": {
|
||||
"files_changed": 2,
|
||||
"insertions": 10,
|
||||
"deletions": 0
|
||||
},
|
||||
"diff": "diff --git a/file.txt b/file.txt\n..."
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user