FEAT: Added Swagger Docs

2026-08-16 23:42:00 +03:00
parent cdc5315401
commit f26ea98b52
8 changed files with 1073 additions and 26 deletions
@@ -6,8 +6,20 @@ import (
 	"net/http"
 )

+type healthResponse struct {
+	Status string `json:"status" example:"ok"`
+}
+
+// Health is the liveness probe the ALB target group polls.
+//
+//	@Summary		Health check
+//	@Description	Reports that the service is up and serving. Used as the ALB target group health check; it does not verify the database or S3 connections.
+//	@Tags			system
+//	@Produce		json
+//	@Success		200	{object}	healthResponse
+//	@Router			/health [get]
 func Health(w http.ResponseWriter, r *http.Request) {
-	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
+	writeJSON(w, http.StatusOK, healthResponse{Status: "ok"})
 }

 // problemDetails is an error body in the RFC 9457 "Problem Details for HTTP
@@ -17,10 +29,10 @@ func Health(w http.ResponseWriter, r *http.Request) {
 // branch on it; Detail explains this particular occurrence and is the only
 // member that varies with request data.
 type problemDetails struct {
-	Type   string `json:"type"`
-	Title  string `json:"title"`
-	Status int    `json:"status"`
-	Detail string `json:"detail,omitempty"`
+	Type   string `json:"type" example:"about:blank"`
+	Title  string `json:"title" example:"Title is required."`
+	Status int    `json:"status" example:"422"`
+	Detail string `json:"detail,omitempty" example:"The 'title' field was absent or contained only whitespace. Every video needs a non-empty title."`
 }

 func writeJSON(w http.ResponseWriter, status int, body any) {
@@ -20,9 +20,18 @@ const (
 )

 type categoriesResponse struct {
-	Categories []string `json:"categories"`
+	Categories []string `json:"categories" example:"documentary,news"`
 }

+// ListCategories returns the categories a video may be assigned to.
+//
+//	@Summary		List video categories
+//	@Description	Returns the fixed lookup set of categories a video can belong to. Values from this list are the only ones accepted in the `categories` field of POST /api/videos.
+//	@Tags			categories
+//	@Produce		json
+//	@Success		200	{object}	categoriesResponse
+//	@Failure		500	{object}	problemDetails	"Categories could not be read from the database"
+//	@Router			/api/categories [get]
 func ListCategories(w http.ResponseWriter, r *http.Request) {
 	categories, err := services.DB.ListCategories(r.Context())
 	if err != nil {
@@ -39,15 +48,28 @@ func ListCategories(w http.ResponseWriter, r *http.Request) {
 }

 type presignRequest struct {
-	FileName    string `json:"fileName"`
-	ContentType string `json:"contentType"`
+	FileName    string `json:"fileName" example:"interview-cut.mov"`
+	ContentType string `json:"contentType" example:"video/quicktime"`
 }

 type presignResponse struct {
-	UploadURL string `json:"uploadUrl"`
-	Key       string `json:"key"`
+	UploadURL string `json:"uploadUrl" example:"https://raw-uploads-bucket.s3.amazonaws.com/videos/a1b2....mov?X-Amz-Signature=..."`
+	Key       string `json:"key" example:"videos/a1b2c3d4e5f6.mov"`
 }

+// PresignVideoUpload issues a presigned S3 PUT URL for a video upload.
+//
+//	@Summary		Create a presigned upload URL
+//	@Description	Step 1 of the upload flow. Returns a short-lived presigned S3 URL that the client PUTs the video file to directly, plus the storage key identifying it. Once the PUT succeeds, pass that same key to POST /api/videos to register the video and start transcoding. The file itself never passes through this API.
+//	@Tags			videos
+//	@Accept			json
+//	@Produce		json
+//	@Param			request	body		presignRequest	true	"Name and media type of the file to be uploaded. contentType must be a video/* type."
+//	@Success		200		{object}	presignResponse
+//	@Failure		400		{object}	problemDetails	"Request body was not valid JSON"
+//	@Failure		422		{object}	problemDetails	"contentType was not a video/* media type"
+//	@Failure		500		{object}	problemDetails	"Upload URL could not be issued"
+//	@Router			/api/videos/presign [post]
 func PresignVideoUpload(w http.ResponseWriter, r *http.Request) {
 	r.Body = http.MaxBytesReader(w, r.Body, maxJSONBodySize)

@@ -83,29 +105,42 @@ func PresignVideoUpload(w http.ResponseWriter, r *http.Request) {
 }

 type completeRequest struct {
-	Title       string   `json:"title"`
-	Description string   `json:"description"`
-	Categories  []string `json:"categories"`
-	Tags        string   `json:"tags"`
-	FileName    string   `json:"fileName"`
-	Key         string   `json:"key"`
+	Title       string   `json:"title" example:"Inside the Newsroom"`
+	Description string   `json:"description" example:"A behind-the-scenes look at the evening bulletin."`
+	Categories  []string `json:"categories" example:"documentary,news"`
+	Tags        string   `json:"tags" example:"media, press, riyadh"`
+	FileName    string   `json:"fileName" example:"interview-cut.mov"`
+	Key         string   `json:"key" example:"videos/a1b2c3d4e5f6.mov"`
 }

 type videoResponse struct {
-	ID                string    `json:"id"`
-	Title             string    `json:"title"`
-	Description       string    `json:"description"`
-	Categories        []string  `json:"categories"`
-	Tags              string    `json:"tags"`
-	FileName          string    `json:"fileName"`
-	StorageKey        string    `json:"storageKey"`
-	MediaConvertJobID string    `json:"mediaConvertJobId"`
-	Status            string    `json:"status"`
-	SizeBytes         int64     `json:"sizeBytes"`
+	ID                string    `json:"id" example:"0199f3a1-7c2e-7b21-9f0d-1a2b3c4d5e6f"`
+	Title             string    `json:"title" example:"Inside the Newsroom"`
+	Description       string    `json:"description" example:"A behind-the-scenes look at the evening bulletin."`
+	Categories        []string  `json:"categories" example:"documentary,news"`
+	Tags              string    `json:"tags" example:"media, press, riyadh"`
+	FileName          string    `json:"fileName" example:"interview-cut.mov"`
+	StorageKey        string    `json:"storageKey" example:"videos/a1b2c3d4e5f6.mov"`
+	MediaConvertJobID string    `json:"mediaConvertJobId" example:"1755300000000-abcdef"`
+	Status            string    `json:"status" example:"processing"`
+	SizeBytes         int64     `json:"sizeBytes" example:"60"`
 	CreatedAt         time.Time `json:"createdAt"`
 	UpdatedAt         time.Time `json:"updatedAt"`
 }

+// CompleteVideoUpload registers an uploaded video and queues it for transcoding.
+//
+//	@Summary		Register an uploaded video
+//	@Description	Step 2 of the upload flow. Takes the storage key returned by POST /api/videos/presign — after the file has been PUT to the presigned URL — submits a MediaConvert transcoding job, and persists the video with its category links. The returned record has status "processing"; note that nothing currently updates that status once transcoding finishes.
+//	@Tags			videos
+//	@Accept			json
+//	@Produce		json
+//	@Param			request	body		completeRequest	true	"Video metadata plus the storage key from the presign step. title and key are required; categories must be values from GET /api/categories."
+//	@Success		201		{object}	videoResponse
+//	@Failure		400		{object}	problemDetails	"Request body was not valid JSON"
+//	@Failure		422		{object}	problemDetails	"title was empty, or key was missing or not a key issued by this API"
+//	@Failure		500		{object}	problemDetails	"Transcoding job could not be queued, or the video record could not be saved"
+//	@Router			/api/videos [post]
 func CompleteVideoUpload(w http.ResponseWriter, r *http.Request) {
 	r.Body = http.MaxBytesReader(w, r.Body, maxJSONBodySize)