From b5aed5928b4658f8803ab3bd8829910e66280eb2 Mon Sep 17 00:00:00 2001 From: Nik Afiq Date: Sat, 22 Nov 2025 21:33:26 +0900 Subject: [PATCH] added docs --- backend/docs/docs.go | 311 ++++++++++++++++++++++++++++++++++++++ backend/docs/swagger.json | 291 +++++++++++++++++++++++++++++++++++ backend/docs/swagger.yaml | 193 +++++++++++++++++++++++ 3 files changed, 795 insertions(+) create mode 100644 backend/docs/docs.go create mode 100644 backend/docs/swagger.json create mode 100644 backend/docs/swagger.yaml diff --git a/backend/docs/docs.go b/backend/docs/docs.go new file mode 100644 index 0000000..d269b2a --- /dev/null +++ b/backend/docs/docs.go @@ -0,0 +1,311 @@ +// Package docs Code generated by swaggo/swag. DO NOT EDIT +package docs + +import "github.com/swaggo/swag" + +const docTemplate = `{ + "schemes": {{ marshal .Schemes }}, + "swagger": "2.0", + "info": { + "description": "{{escape .Description}}", + "title": "{{.Title}}", + "contact": {}, + "version": "{{.Version}}" + }, + "host": "{{.Host}}", + "basePath": "{{.BasePath}}", + "paths": { + "/api/v1/archive": { + "post": { + "description": "Move one or many IDs from ` + "`" + `current` + "`" + ` to ` + "`" + `current_archive` + "`" + `.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "archive" + ], + "summary": "Move shows to archive", + "parameters": [ + { + "description": "IDs to move", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/httpapi.MoveReq" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/httpapi.MoveRes" + } + }, + "400": { + "description": "empty ids", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "500": { + "description": "move failed", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + } + } + } + }, + "/api/v1/current": { + "get": { + "description": "Returns the current row from ` + "`" + `current` + "`" + ` table.", + "produces": [ + "application/json" + ], + "tags": [ + "current" + ], + "summary": "Get current show", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/httpapi.CurrentResponse" + } + }, + "404": { + "description": "no current row found", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "500": { + "description": "query failed", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + } + } + }, + "post": { + "description": "Set the current show ID and start time.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "current" + ], + "summary": "Set current show", + "parameters": [ + { + "description": "Current show payload", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/httpapi.SetCurrentReq" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/httpapi.CurrentResponse" + } + }, + "400": { + "description": "invalid payload or invalid time", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "404": { + "description": "id not found", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "500": { + "description": "update failed", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + } + } + } + }, + "/api/v1/shows": { + "get": { + "description": "List all rows from ` + "`" + `current` + "`" + ` table.", + "produces": [ + "application/json" + ], + "tags": [ + "shows" + ], + "summary": "List current shows", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/httpapi.CurrentResponse" + } + } + }, + "500": { + "description": "list failed", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + } + } + }, + "delete": { + "description": "Delete a row from ` + "`" + `current` + "`" + ` by ID.", + "produces": [ + "application/json" + ], + "tags": [ + "shows" + ], + "summary": "Delete show", + "parameters": [ + { + "type": "integer", + "format": "int64", + "description": "Show ID", + "name": "id", + "in": "query", + "required": true + } + ], + "responses": { + "204": { + "description": "No Content" + }, + "400": { + "description": "invalid id", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "404": { + "description": "id not found", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "500": { + "description": "delete failed", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + } + } + } + } + }, + "definitions": { + "httpapi.CurrentResponse": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "start_time": { + "type": "string" + } + } + }, + "httpapi.HTTPError": { + "type": "object", + "properties": { + "error": { + "type": "string", + "example": "invalid payload" + } + } + }, + "httpapi.MoveReq": { + "type": "object" + }, + "httpapi.MoveRes": { + "type": "object", + "properties": { + "deleted": { + "type": "integer" + }, + "deleted_ids": { + "type": "array", + "items": { + "type": "integer" + } + }, + "inserted": { + "type": "integer" + }, + "moved_ids": { + "type": "array", + "items": { + "type": "integer" + } + }, + "skipped": { + "type": "integer" + }, + "skipped_ids": { + "type": "array", + "items": { + "type": "integer" + } + } + } + }, + "httpapi.SetCurrentReq": { + "type": "object", + "required": [ + "id", + "start_time" + ], + "properties": { + "id": { + "type": "integer", + "example": 123 + }, + "start_time": { + "type": "string", + "example": "21:00:00" + } + } + } + } +}` + +// SwaggerInfo holds exported Swagger Info so clients can modify it +var SwaggerInfo = &swag.Spec{ + Version: "1.0", + Host: "localhost:8082", + BasePath: "/", + Schemes: []string{"http", "https"}, + Title: "Watch Party Backend API", + Description: "Backend API for watch-party app.", + InfoInstanceName: "swagger", + SwaggerTemplate: docTemplate, + LeftDelim: "{{", + RightDelim: "}}", +} + +func init() { + swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo) +} diff --git a/backend/docs/swagger.json b/backend/docs/swagger.json new file mode 100644 index 0000000..2856d69 --- /dev/null +++ b/backend/docs/swagger.json @@ -0,0 +1,291 @@ +{ + "schemes": [ + "http", + "https" + ], + "swagger": "2.0", + "info": { + "description": "Backend API for watch-party app.", + "title": "Watch Party Backend API", + "contact": {}, + "version": "1.0" + }, + "host": "localhost:8082", + "basePath": "/", + "paths": { + "/api/v1/archive": { + "post": { + "description": "Move one or many IDs from `current` to `current_archive`.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "archive" + ], + "summary": "Move shows to archive", + "parameters": [ + { + "description": "IDs to move", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/httpapi.MoveReq" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/httpapi.MoveRes" + } + }, + "400": { + "description": "empty ids", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "500": { + "description": "move failed", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + } + } + } + }, + "/api/v1/current": { + "get": { + "description": "Returns the current row from `current` table.", + "produces": [ + "application/json" + ], + "tags": [ + "current" + ], + "summary": "Get current show", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/httpapi.CurrentResponse" + } + }, + "404": { + "description": "no current row found", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "500": { + "description": "query failed", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + } + } + }, + "post": { + "description": "Set the current show ID and start time.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "current" + ], + "summary": "Set current show", + "parameters": [ + { + "description": "Current show payload", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/httpapi.SetCurrentReq" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/httpapi.CurrentResponse" + } + }, + "400": { + "description": "invalid payload or invalid time", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "404": { + "description": "id not found", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "500": { + "description": "update failed", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + } + } + } + }, + "/api/v1/shows": { + "get": { + "description": "List all rows from `current` table.", + "produces": [ + "application/json" + ], + "tags": [ + "shows" + ], + "summary": "List current shows", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/httpapi.CurrentResponse" + } + } + }, + "500": { + "description": "list failed", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + } + } + }, + "delete": { + "description": "Delete a row from `current` by ID.", + "produces": [ + "application/json" + ], + "tags": [ + "shows" + ], + "summary": "Delete show", + "parameters": [ + { + "type": "integer", + "format": "int64", + "description": "Show ID", + "name": "id", + "in": "query", + "required": true + } + ], + "responses": { + "204": { + "description": "No Content" + }, + "400": { + "description": "invalid id", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "404": { + "description": "id not found", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + }, + "500": { + "description": "delete failed", + "schema": { + "$ref": "#/definitions/httpapi.HTTPError" + } + } + } + } + } + }, + "definitions": { + "httpapi.CurrentResponse": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "start_time": { + "type": "string" + } + } + }, + "httpapi.HTTPError": { + "type": "object", + "properties": { + "error": { + "type": "string", + "example": "invalid payload" + } + } + }, + "httpapi.MoveReq": { + "type": "object" + }, + "httpapi.MoveRes": { + "type": "object", + "properties": { + "deleted": { + "type": "integer" + }, + "deleted_ids": { + "type": "array", + "items": { + "type": "integer" + } + }, + "inserted": { + "type": "integer" + }, + "moved_ids": { + "type": "array", + "items": { + "type": "integer" + } + }, + "skipped": { + "type": "integer" + }, + "skipped_ids": { + "type": "array", + "items": { + "type": "integer" + } + } + } + }, + "httpapi.SetCurrentReq": { + "type": "object", + "required": [ + "id", + "start_time" + ], + "properties": { + "id": { + "type": "integer", + "example": 123 + }, + "start_time": { + "type": "string", + "example": "21:00:00" + } + } + } + } +} \ No newline at end of file diff --git a/backend/docs/swagger.yaml b/backend/docs/swagger.yaml new file mode 100644 index 0000000..f7aab59 --- /dev/null +++ b/backend/docs/swagger.yaml @@ -0,0 +1,193 @@ +basePath: / +definitions: + httpapi.CurrentResponse: + properties: + id: + type: integer + start_time: + type: string + type: object + httpapi.HTTPError: + properties: + error: + example: invalid payload + type: string + type: object + httpapi.MoveReq: + type: object + httpapi.MoveRes: + properties: + deleted: + type: integer + deleted_ids: + items: + type: integer + type: array + inserted: + type: integer + moved_ids: + items: + type: integer + type: array + skipped: + type: integer + skipped_ids: + items: + type: integer + type: array + type: object + httpapi.SetCurrentReq: + properties: + id: + example: 123 + type: integer + start_time: + example: "21:00:00" + type: string + required: + - id + - start_time + type: object +host: localhost:8082 +info: + contact: {} + description: Backend API for watch-party app. + title: Watch Party Backend API + version: "1.0" +paths: + /api/v1/archive: + post: + consumes: + - application/json + description: Move one or many IDs from `current` to `current_archive`. + parameters: + - description: IDs to move + in: body + name: body + required: true + schema: + $ref: '#/definitions/httpapi.MoveReq' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/httpapi.MoveRes' + "400": + description: empty ids + schema: + $ref: '#/definitions/httpapi.HTTPError' + "500": + description: move failed + schema: + $ref: '#/definitions/httpapi.HTTPError' + summary: Move shows to archive + tags: + - archive + /api/v1/current: + get: + description: Returns the current row from `current` table. + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/httpapi.CurrentResponse' + "404": + description: no current row found + schema: + $ref: '#/definitions/httpapi.HTTPError' + "500": + description: query failed + schema: + $ref: '#/definitions/httpapi.HTTPError' + summary: Get current show + tags: + - current + post: + consumes: + - application/json + description: Set the current show ID and start time. + parameters: + - description: Current show payload + in: body + name: body + required: true + schema: + $ref: '#/definitions/httpapi.SetCurrentReq' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/httpapi.CurrentResponse' + "400": + description: invalid payload or invalid time + schema: + $ref: '#/definitions/httpapi.HTTPError' + "404": + description: id not found + schema: + $ref: '#/definitions/httpapi.HTTPError' + "500": + description: update failed + schema: + $ref: '#/definitions/httpapi.HTTPError' + summary: Set current show + tags: + - current + /api/v1/shows: + delete: + description: Delete a row from `current` by ID. + parameters: + - description: Show ID + format: int64 + in: query + name: id + required: true + type: integer + produces: + - application/json + responses: + "204": + description: No Content + "400": + description: invalid id + schema: + $ref: '#/definitions/httpapi.HTTPError' + "404": + description: id not found + schema: + $ref: '#/definitions/httpapi.HTTPError' + "500": + description: delete failed + schema: + $ref: '#/definitions/httpapi.HTTPError' + summary: Delete show + tags: + - shows + get: + description: List all rows from `current` table. + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/httpapi.CurrentResponse' + type: array + "500": + description: list failed + schema: + $ref: '#/definitions/httpapi.HTTPError' + summary: List current shows + tags: + - shows +schemes: +- http +- https +swagger: "2.0"