drexa/drive
1
0
Fork 0
mirror of https://github.com/get-drexa/drive.git synced 2026-02-02 14:41:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add OpenAPI documentation with Scalar UI

Browse Source 
- Add swaggo annotations to all HTTP handlers
- Add Swagger/OpenAPI spec generation with swag
- Create separate docs server binary (drexa-docs)
- Add Makefile with build, run, and docs targets
- Configure Scalar as the API documentation UI

Run 'make docs' to regenerate, 'make run-docs' to serve.
This commit is contained in:
Kenneth
2025-12-13 22:44:37 +00:00
parent 918b85dfd5
commit 7b13326e22
18 changed files with 4853 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
apps/backend/internal/upload/http.go
View File

@@ -10,13 +10,20 @@ import (
"github.com/uptrace/bun"
)
// createUploadRequest represents a new upload session request
// @Description Request to initiate a file upload
type createUploadRequest struct {
ParentID string `json:"parentId"`
Name string `json:"name"`
// ID of the parent directory to upload into
ParentID string `json:"parentId" example:"kRp2XYTq9A55"`
// Name of the file being uploaded
Name string `json:"name" example:"document.pdf"`
}
// updateUploadRequest represents an upload status update
// @Description Request to update upload status (e.g., mark as completed)
type updateUploadRequest struct {
Status Status `json:"status"`
// New status for the upload
Status Status `json:"status" example:"completed" enums:"completed"`
}
type HTTPHandler struct {
@@ -36,6 +43,21 @@ func (h *HTTPHandler) RegisterRoutes(api fiber.Router) {
upload.Patch("/:uploadID", h.Update)
}
// Create initiates a new file upload session
// @Summary Create upload session
// @Description Start a new file upload session. Returns an upload URL to PUT file content to.
// @Tags uploads
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param accountID path string true "Account ID" format(uuid)
// @Param request body createUploadRequest true "Upload details"
// @Success 200 {object} Upload "Upload session created"
// @Failure 400 {object} map[string]string "Parent is not a directory"
// @Failure 401 {string} string "Not authenticated"
// @Failure 404 {string} string "Parent directory not found"
// @Failure 409 {object} map[string]string "File with this name already exists"
// @Router /accounts/{accountID}/uploads [post]
func (h *HTTPHandler) Create(c *fiber.Ctx) error {
account := account.CurrentAccount(c)
if account == nil {
@@ -71,6 +93,19 @@ func (h *HTTPHandler) Create(c *fiber.Ctx) error {
return c.JSON(upload)
}
// ReceiveContent receives the file content for an upload
// @Summary Upload file content
// @Description Stream file content to complete an upload. Send raw binary data in the request body.
// @Tags uploads
// @Accept application/octet-stream
// @Security BearerAuth
// @Param accountID path string true "Account ID" format(uuid)
// @Param uploadID path string true "Upload session ID"
// @Param file body []byte true "File content (binary)"
// @Success 204 {string} string "Content received successfully"
// @Failure 401 {string} string "Not authenticated"
// @Failure 404 {string} string "Upload session not found"
// @Router /accounts/{accountID}/uploads/{uploadID}/content [put]
func (h *HTTPHandler) ReceiveContent(c *fiber.Ctx) error {
account := account.CurrentAccount(c)
if account == nil {
@@ -91,6 +126,21 @@ func (h *HTTPHandler) ReceiveContent(c *fiber.Ctx) error {
return c.SendStatus(fiber.StatusNoContent)
}
// Update updates the upload status
// @Summary Complete upload
// @Description Mark an upload as completed after content has been uploaded. This finalizes the file in the filesystem.
// @Tags uploads
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param accountID path string true "Account ID" format(uuid)
// @Param uploadID path string true "Upload session ID"
// @Param request body updateUploadRequest true "Status update"
// @Success 200 {object} Upload "Upload completed"
// @Failure 400 {object} map[string]string "Content not uploaded yet or invalid status"
// @Failure 401 {string} string "Not authenticated"
// @Failure 404 {string} string "Upload session not found"
// @Router /accounts/{accountID}/uploads/{uploadID} [patch]
func (h *HTTPHandler) Update(c *fiber.Ctx) error {
account := account.CurrentAccount(c)
if account == nil {