{ "swagger": "2.0", "info": { "description": "API documentation for GoGin", "title": "GoGin API", "contact": {}, "version": "1.0" }, "host": "localhost:8080", "basePath": "/", "paths": { "/api/v1/admin/categories": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Admin listing of categories. Use ?soft=only to list only deleted, ?soft=with to include deleted, omit to exclude deleted.", "produces": [ "application/json" ], "tags": [ "categories" ], "summary": "Admin: List categories (supports soft-delete filter)", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Soft delete filter: only|with", "name": "soft", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new category (admin)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "categories" ], "summary": "Create a category", "parameters": [ { "description": "Category payload", "name": "category", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CategoryPayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/controllers.CategorySimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/categories/deleted": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List categories that have been soft-deleted with pagination", "produces": [ "application/json" ], "tags": [ "categories" ], "summary": "List soft-deleted categories", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/categories/{id}": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Update an existing category (admin)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "categories" ], "summary": "Update a category", "parameters": [ { "type": "integer", "description": "Category ID", "name": "id", "in": "path", "required": true }, { "description": "Category payload", "name": "category", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CategoryPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.CategorySimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft-delete a category (admin)", "produces": [ "application/json" ], "tags": [ "categories" ], "summary": "Delete a category", "parameters": [ { "type": "integer", "description": "Category ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/categories/{id}/posts": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a post and attach it to the given category", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "categories" ], "summary": "Add a post to a category (admin)", "parameters": [ { "type": "integer", "description": "Category ID", "name": "id", "in": "path", "required": true }, { "description": "Post payload", "name": "post", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.PostPayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/controllers.PostResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/categories/{id}/restore": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Restore a category and related posts/comments if soft-deleted", "produces": [ "application/json" ], "tags": [ "categories" ], "summary": "Restore a soft-deleted category", "parameters": [ { "type": "integer", "description": "Category ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.CategorySimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/categoryviews": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Admin listing of category views. Use ?soft=only to list only deleted, ?soft=with to include deleted, omit to exclude deleted.", "produces": [ "application/json" ], "tags": [ "categoryviews" ], "summary": "Admin: List category views (supports soft-delete filter)", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Soft delete filter: only|with", "name": "soft", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a category view as admin", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "categoryviews" ], "summary": "Create a category view (admin)", "parameters": [ { "description": "CategoryView payload", "name": "view", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CategoryViewPayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/controllers.CategoryViewSimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/comments": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Admin listing of comments. Use ?soft=only to list only deleted, ?soft=with to include deleted, omit to exclude deleted.", "produces": [ "application/json" ], "tags": [ "comments" ], "summary": "Admin: List comments (supports soft-delete filter)", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Soft delete filter: only|with", "name": "soft", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a comment as admin", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "comments" ], "summary": "Create a comment (admin)", "parameters": [ { "description": "Comment payload", "name": "comment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CommentPayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/controllers.CommentSimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/comments/{id}": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Update a comment as admin", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "comments" ], "summary": "Update a comment (admin)", "parameters": [ { "type": "integer", "description": "Comment ID", "name": "id", "in": "path", "required": true }, { "description": "Comment payload", "name": "comment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CommentPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.CommentSimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft-delete a comment as admin", "produces": [ "application/json" ], "tags": [ "comments" ], "summary": "Delete a comment (admin)", "parameters": [ { "type": "integer", "description": "Comment ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/heroes": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Admin listing of heroes. Use ?soft=only to list deleted, ?soft=with to include deleted.", "produces": [ "application/json" ], "tags": [ "heroes" ], "summary": "Admin: List heroes", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Soft delete filter: only|with", "name": "soft", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.HeroListResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new hero item (multipart/form-data)", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "heroes" ], "summary": "Admin: Create a hero", "parameters": [ { "type": "string", "description": "Color", "name": "color", "in": "formData", "required": true }, { "type": "string", "description": "Title", "name": "title", "in": "formData" }, { "type": "string", "description": "Text1", "name": "text1", "in": "formData" }, { "type": "string", "description": "Text2", "name": "text2", "in": "formData" }, { "type": "string", "description": "Text4", "name": "text4", "in": "formData" }, { "type": "string", "description": "Text5", "name": "text5", "in": "formData" }, { "type": "boolean", "description": "Is Active", "name": "is_active", "in": "formData" }, { "type": "integer", "description": "Image width (frontend-provided)", "name": "width", "in": "formData" }, { "type": "integer", "description": "Image height (frontend-provided)", "name": "height", "in": "formData" }, { "type": "integer", "description": "Image quality (frontend-provided)", "name": "quality", "in": "formData" }, { "type": "string", "description": "Image format (jpeg|png|webp) (frontend-provided)", "name": "format", "in": "formData" }, { "type": "file", "description": "Image file", "name": "image", "in": "formData" } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/controllers.HeroResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/heroes/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Return a single hero by id", "produces": [ "application/json" ], "tags": [ "heroes" ], "summary": "Admin: Get a hero by id", "parameters": [ { "type": "integer", "description": "Hero ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.HeroResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update an existing hero (multipart/form-data)", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "heroes" ], "summary": "Admin: Update a hero", "parameters": [ { "type": "integer", "description": "Hero ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Color", "name": "color", "in": "formData" }, { "type": "string", "description": "Title", "name": "title", "in": "formData" }, { "type": "string", "description": "Text1", "name": "text1", "in": "formData" }, { "type": "string", "description": "Text2", "name": "text2", "in": "formData" }, { "type": "string", "description": "Text4", "name": "text4", "in": "formData" }, { "type": "string", "description": "Text5", "name": "text5", "in": "formData" }, { "type": "boolean", "description": "Is Active", "name": "is_active", "in": "formData" }, { "type": "integer", "description": "Image width (frontend-provided)", "name": "width", "in": "formData" }, { "type": "integer", "description": "Image height (frontend-provided)", "name": "height", "in": "formData" }, { "type": "integer", "description": "Image quality (frontend-provided)", "name": "quality", "in": "formData" }, { "type": "string", "description": "Image format (jpeg|png|webp) (frontend-provided)", "name": "format", "in": "formData" }, { "type": "file", "description": "Image file", "name": "image", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.HeroResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft-delete a hero by ID", "produces": [ "application/json" ], "tags": [ "heroes" ], "summary": "Admin: Delete a hero", "parameters": [ { "type": "integer", "description": "Hero ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/heroes/{id}/restore": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Restore a soft-deleted hero by ID", "produces": [ "application/json" ], "tags": [ "heroes" ], "summary": "Admin: Restore a soft-deleted hero", "parameters": [ { "type": "integer", "description": "Hero ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.HeroResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/posts": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Admin listing of posts. Use ?soft=only to list only deleted, ?soft=with to include deleted, omit to exclude deleted.", "produces": [ "application/json" ], "tags": [ "posts" ], "summary": "Admin: List posts (supports soft-delete filter)", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "integer", "description": "Filter by category id", "name": "category_id", "in": "query" }, { "type": "integer", "description": "Filter by tag id", "name": "tag_id", "in": "query" }, { "type": "string", "description": "Search query", "name": "q", "in": "query" }, { "type": "string", "description": "Soft delete filter: only|with", "name": "soft", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.PostListResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new blog post (supports multipart/form-data with image upload)", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "posts" ], "summary": "Create a post", "parameters": [ { "type": "string", "description": "Title", "name": "title", "in": "formData", "required": true }, { "type": "string", "description": "Slug", "name": "slug", "in": "formData" }, { "type": "string", "description": "Content", "name": "content", "in": "formData" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Category IDs (repeatable)", "name": "category_ids", "in": "formData" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "Tag names (repeatable)", "name": "tag_names", "in": "formData" }, { "type": "file", "description": "Image files (use 'images' or 'image' fields)", "name": "images", "in": "formData" }, { "type": "integer", "description": "Image width", "name": "width", "in": "formData" }, { "type": "integer", "description": "Image height", "name": "height", "in": "formData" }, { "type": "integer", "description": "Image quality", "name": "quality", "in": "formData" }, { "type": "string", "description": "Image format", "name": "format", "in": "formData" } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/controllers.PostResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/posts/deleted": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List posts that have been soft-deleted with pagination", "produces": [ "application/json" ], "tags": [ "posts" ], "summary": "List soft-deleted posts", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.PostListResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/posts/{id}": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Update an existing blog post (supports multipart/form-data with image upload)", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "posts" ], "summary": "Update a post", "parameters": [ { "type": "integer", "description": "Post ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Title", "name": "title", "in": "formData" }, { "type": "string", "description": "Slug", "name": "slug", "in": "formData" }, { "type": "string", "description": "Content", "name": "content", "in": "formData" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Category IDs (repeatable)", "name": "category_ids", "in": "formData" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "Tag names (repeatable)", "name": "tag_names", "in": "formData" }, { "type": "file", "description": "Image files (use 'images' or 'image' fields)", "name": "images", "in": "formData" }, { "type": "integer", "description": "Image width", "name": "width", "in": "formData" }, { "type": "integer", "description": "Image height", "name": "height", "in": "formData" }, { "type": "integer", "description": "Image quality", "name": "quality", "in": "formData" }, { "type": "string", "description": "Image format", "name": "format", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.PostResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Delete a blog post by ID", "produces": [ "application/json" ], "tags": [ "posts" ], "summary": "Delete a post", "parameters": [ { "type": "integer", "description": "Post ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/posts/{id}/comments": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Add a comment to a specific post as admin", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "posts" ], "summary": "Add a comment to a post (admin)", "parameters": [ { "type": "integer", "description": "Post ID", "name": "id", "in": "path", "required": true }, { "description": "Comment payload", "name": "comment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CommentPayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/controllers.CommentSimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/posts/{id}/restore": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Restore a post and its related comments (if soft-deleted)", "produces": [ "application/json" ], "tags": [ "posts" ], "summary": "Restore a soft-deleted post", "parameters": [ { "type": "integer", "description": "Post ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.PostResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/settings": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Admin listing of settings. Use ?soft=only to list deleted, ?soft=with to include deleted.", "produces": [ "application/json" ], "tags": [ "settings" ], "summary": "Admin: List settings", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Soft delete filter: only|with", "name": "soft", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.SettingListResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new setting", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "settings" ], "summary": "Admin: Create a setting", "parameters": [ { "type": "string", "description": "Title", "name": "title", "in": "formData", "required": true }, { "type": "string", "description": "Meta title", "name": "meta_title", "in": "formData", "required": true }, { "type": "string", "description": "Meta description", "name": "meta_description", "in": "formData", "required": true }, { "type": "string", "description": "Phone", "name": "phone", "in": "formData", "required": true }, { "type": "string", "description": "URL", "name": "url", "in": "formData", "required": true }, { "type": "string", "description": "Email", "name": "email", "in": "formData", "required": true }, { "type": "string", "description": "Facebook", "name": "facebook", "in": "formData" }, { "type": "string", "description": "X", "name": "x", "in": "formData" }, { "type": "string", "description": "Instagram", "name": "instagram", "in": "formData" }, { "type": "string", "description": "Whatsapp", "name": "whatsapp", "in": "formData" }, { "type": "string", "description": "Pinterest", "name": "pinterest", "in": "formData" }, { "type": "string", "description": "Linkedin", "name": "linkedin", "in": "formData" }, { "type": "string", "description": "Slogan", "name": "slogan", "in": "formData" }, { "type": "string", "description": "Address", "name": "address", "in": "formData" }, { "type": "string", "description": "Copyright", "name": "copyright", "in": "formData" }, { "type": "string", "description": "Map embed", "name": "map_embed", "in": "formData" }, { "type": "file", "description": "White logo file upload (or provide w_logo path as string)", "name": "w_logo", "in": "formData" }, { "type": "file", "description": "Black logo file upload (or provide b_logo path as string)", "name": "b_logo", "in": "formData" }, { "type": "boolean", "description": "Is active", "name": "is_active", "in": "formData" }, { "type": "integer", "description": "W logo width", "name": "w_width", "in": "formData" }, { "type": "integer", "description": "W logo height", "name": "w_height", "in": "formData" }, { "type": "integer", "description": "W logo quality", "name": "w_quality", "in": "formData" }, { "type": "string", "description": "W logo format", "name": "w_format", "in": "formData" }, { "type": "integer", "description": "B logo width", "name": "b_width", "in": "formData" }, { "type": "integer", "description": "B logo height", "name": "b_height", "in": "formData" }, { "type": "integer", "description": "B logo quality", "name": "b_quality", "in": "formData" }, { "type": "string", "description": "B logo format", "name": "b_format", "in": "formData" } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/controllers.SettingResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/settings/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Return a single setting by id", "produces": [ "application/json" ], "tags": [ "settings" ], "summary": "Admin: Get a setting by id", "parameters": [ { "type": "integer", "description": "Setting ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.SettingResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update an existing setting", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "settings" ], "summary": "Admin: Update a setting", "parameters": [ { "type": "integer", "description": "Setting ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Title", "name": "title", "in": "formData" }, { "type": "string", "description": "Meta title", "name": "meta_title", "in": "formData" }, { "type": "string", "description": "Meta description", "name": "meta_description", "in": "formData" }, { "type": "string", "description": "Phone", "name": "phone", "in": "formData" }, { "type": "string", "description": "URL", "name": "url", "in": "formData" }, { "type": "string", "description": "Email", "name": "email", "in": "formData" }, { "type": "string", "description": "Facebook", "name": "facebook", "in": "formData" }, { "type": "string", "description": "X", "name": "x", "in": "formData" }, { "type": "string", "description": "Instagram", "name": "instagram", "in": "formData" }, { "type": "string", "description": "Whatsapp", "name": "whatsapp", "in": "formData" }, { "type": "string", "description": "Pinterest", "name": "pinterest", "in": "formData" }, { "type": "string", "description": "Linkedin", "name": "linkedin", "in": "formData" }, { "type": "string", "description": "Slogan", "name": "slogan", "in": "formData" }, { "type": "string", "description": "Address", "name": "address", "in": "formData" }, { "type": "string", "description": "Copyright", "name": "copyright", "in": "formData" }, { "type": "string", "description": "Map embed", "name": "map_embed", "in": "formData" }, { "type": "file", "description": "White logo file upload (or provide w_logo path as string)", "name": "w_logo", "in": "formData" }, { "type": "file", "description": "Black logo file upload (or provide b_logo path as string)", "name": "b_logo", "in": "formData" }, { "type": "boolean", "description": "Is active", "name": "is_active", "in": "formData" }, { "type": "integer", "description": "W logo width", "name": "w_width", "in": "formData" }, { "type": "integer", "description": "W logo height", "name": "w_height", "in": "formData" }, { "type": "integer", "description": "W logo quality", "name": "w_quality", "in": "formData" }, { "type": "string", "description": "W logo format", "name": "w_format", "in": "formData" }, { "type": "integer", "description": "B logo width", "name": "b_width", "in": "formData" }, { "type": "integer", "description": "B logo height", "name": "b_height", "in": "formData" }, { "type": "integer", "description": "B logo quality", "name": "b_quality", "in": "formData" }, { "type": "string", "description": "B logo format", "name": "b_format", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.SettingResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft-delete a setting by ID", "produces": [ "application/json" ], "tags": [ "settings" ], "summary": "Admin: Delete a setting", "parameters": [ { "type": "integer", "description": "Setting ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/settings/{id}/restore": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Restore a soft-deleted setting by ID", "produces": [ "application/json" ], "tags": [ "settings" ], "summary": "Admin: Restore a soft-deleted setting", "parameters": [ { "type": "integer", "description": "Setting ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.SettingResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/tags": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Admin listing of tags. Use ?soft=only to list only deleted, ?soft=with to include deleted, omit to exclude deleted.", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Admin: List tags (supports soft-delete filter)", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Soft delete filter: only|with", "name": "soft", "in": "query" } ], "responses": { "200": { "description": "items: []AdminTagListItem (includes deleted_at when soft=only or soft=with)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new tag (admin)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Create a tag", "parameters": [ { "description": "Tag payload", "name": "tag", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.TagPayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/controllers.TagSimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/tags/{id}": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Update an existing tag (admin)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Update a tag", "parameters": [ { "type": "integer", "description": "Tag ID", "name": "id", "in": "path", "required": true }, { "description": "Tag payload", "name": "tag", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.TagPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.TagSimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft-delete a tag (admin)", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Delete a tag", "parameters": [ { "type": "integer", "description": "Tag ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/tags/{id}/restore": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Restore a tag that has been soft-deleted (admin)", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Restore a soft-deleted tag", "parameters": [ { "type": "integer", "description": "Tag ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.TagSimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/users": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Admin listing of users with pagination and search", "produces": [ "application/json" ], "tags": [ "users_admin" ], "summary": "Admin: List users", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Search query (username or email)", "name": "q", "in": "query" }, { "type": "string", "description": "Soft delete filter: only|with", "name": "soft", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/users/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get user details by ID", "produces": [ "application/json" ], "tags": [ "users_admin" ], "summary": "Admin: Get user", "parameters": [ { "type": "integer", "description": "User ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.UserResponse" } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update user details (admin)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users_admin" ], "summary": "Admin: Update user", "parameters": [ { "type": "integer", "description": "User ID", "name": "id", "in": "path", "required": true }, { "description": "User update payload", "name": "user", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.AdminUserUpdatePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.UserResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft delete user", "produces": [ "application/json" ], "tags": [ "users_admin" ], "summary": "Admin: Delete user", "parameters": [ { "type": "integer", "description": "User ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/admin/users/{id}/restore": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Restore soft-deleted user", "produces": [ "application/json" ], "tags": [ "users_admin" ], "summary": "Admin: Restore user", "parameters": [ { "type": "integer", "description": "User ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.UserResponse" } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/auth/github": { "get": { "description": "Redirects to GitHub for authentication", "tags": [ "auth" ], "summary": "GitHub OAuth2 Login", "responses": { "302": { "description": "Found" } } } }, "/api/v1/auth/github/callback": { "get": { "description": "Handles GitHub OAuth2 callback", "tags": [ "auth" ], "summary": "GitHub OAuth2 Callback", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.AuthResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/auth/google": { "get": { "description": "Redirects to Google for authentication", "tags": [ "auth" ], "summary": "Google OAuth2 Login", "responses": { "302": { "description": "Found" } } } }, "/api/v1/auth/google/callback": { "get": { "description": "Handles Google OAuth2 callback", "tags": [ "auth" ], "summary": "Google OAuth2 Callback", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.AuthResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/auth/login": { "post": { "description": "Login with email and password, returns tokens", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Login user", "parameters": [ { "description": "Login payload", "name": "login", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.LoginPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.AuthResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/auth/me": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get current authenticated user information", "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Get current user (me)", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/auth/refresh": { "post": { "description": "usage: send refresh token to get new access token and refresh token", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Refresh access token", "parameters": [ { "description": "Refresh token payload", "name": "refresh", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.RefreshPayload" } } ], "responses": { "200": { "description": "Returns both access_token and refresh_token", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/auth/register": { "post": { "description": "Register a new user. Sends verification email. Does NOT return tokens.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Register a new user", "parameters": [ { "description": "Register payload", "name": "register", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.RegisterPayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/controllers.AuthResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/auth/verify-email": { "get": { "description": "Verify email using token", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Verify email address", "parameters": [ { "type": "string", "description": "Verification Token", "name": "token", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/categories": { "get": { "description": "List categories with pagination", "produces": [ "application/json" ], "tags": [ "categories" ], "summary": "List categories", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/categoryviews": { "get": { "description": "List category views with pagination", "produces": [ "application/json" ], "tags": [ "categoryviews" ], "summary": "List category views", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/categoryviews/{id}": { "get": { "description": "Return a single category view by id", "produces": [ "application/json" ], "tags": [ "categoryviews" ], "summary": "Get a category view by id", "parameters": [ { "type": "integer", "description": "CategoryView ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.CategoryViewSimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/comments": { "get": { "description": "List comments with pagination", "produces": [ "application/json" ], "tags": [ "comments" ], "summary": "List comments", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/comments/{id}": { "get": { "description": "Return a single comment by id", "produces": [ "application/json" ], "tags": [ "comments" ], "summary": "Get a comment by id", "parameters": [ { "type": "integer", "description": "Comment ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.CommentSimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/heroes": { "get": { "description": "Return active heroes with pagination", "produces": [ "application/json" ], "tags": [ "heroes" ], "summary": "Public: List heroes", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.HeroListResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/heroes/{id}": { "get": { "description": "Return a single hero by id", "produces": [ "application/json" ], "tags": [ "heroes" ], "summary": "Public: Get a hero by id", "parameters": [ { "type": "integer", "description": "Hero ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.HeroResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/posts": { "get": { "description": "List posts with pagination and optional filters", "produces": [ "application/json" ], "tags": [ "posts" ], "summary": "List posts", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" }, { "type": "integer", "description": "Filter by category id", "name": "category_id", "in": "query" }, { "type": "integer", "description": "Filter by tag id", "name": "tag_id", "in": "query" }, { "type": "string", "description": "Search query", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.PostListResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/posts/{slug}": { "get": { "description": "Return a single post found by slug", "produces": [ "application/json" ], "tags": [ "posts" ], "summary": "Get a post by slug", "parameters": [ { "type": "string", "description": "Post slug", "name": "slug", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.PostResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/settings": { "get": { "description": "Return the active site setting (latest active). If none active, return latest setting.", "produces": [ "application/json" ], "tags": [ "settings" ], "summary": "Public: Get site settings", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.SettingResponse" } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/tags": { "get": { "description": "List tags with pagination", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "List tags", "parameters": [ { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/tags/{id}": { "get": { "description": "Return a single tag by id", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Get a tag by id", "parameters": [ { "type": "integer", "description": "Tag ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.TagSimple" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/users/profile": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Get profile of the logged-in user", "produces": [ "application/json" ], "tags": [ "users" ], "summary": "Get current user profile", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.UserResponse" } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Update profile of the logged-in user", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "users" ], "summary": "Update current user profile", "parameters": [ { "description": "User update payload", "name": "user", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UserPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.UserResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "definitions": { "controllers.AdminUserUpdatePayload": { "type": "object", "properties": { "email": { "type": "string" }, "is_admin": { "description": "Pointer allows checking if field is present", "type": "boolean" }, "username": { "type": "string" } } }, "controllers.AuthResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "user": { "$ref": "#/definitions/controllers.UserResponse" } } }, "controllers.CategoryPayload": { "type": "object", "required": [ "title" ], "properties": { "description": { "type": "string" }, "parent_id": { "type": "integer" }, "slug": { "type": "string" }, "title": { "type": "string" } } }, "controllers.CategorySimple": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "parent_id": { "type": "integer" }, "slug": { "type": "string", "example": "news" }, "title": { "type": "string", "example": "News" } } }, "controllers.CategoryViewPayload": { "type": "object", "required": [ "category_id" ], "properties": { "category_id": { "type": "integer" }, "ip_address": { "type": "string" } } }, "controllers.CategoryViewSimple": { "type": "object", "properties": { "category_id": { "type": "integer", "example": 1 }, "created_at": { "type": "string" }, "id": { "type": "integer", "example": 1 }, "ip_address": { "type": "string", "example": "127.0.0.1" } } }, "controllers.CommentPayload": { "type": "object", "required": [ "body", "post_id", "user_id" ], "properties": { "body": { "type": "string" }, "post_id": { "type": "integer" }, "user_id": { "type": "integer" } } }, "controllers.CommentSimple": { "type": "object", "properties": { "body": { "type": "string", "example": "Nice post" }, "created_at": { "type": "string" }, "id": { "type": "integer", "example": 1 }, "post_id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 2 } } }, "controllers.HeroListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/controllers.HeroResponse" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "controllers.HeroResponse": { "type": "object", "properties": { "color": { "type": "string", "example": "#ffffff" }, "created_at": { "type": "string" }, "format": { "type": "string", "example": "jpeg" }, "height": { "type": "integer", "example": 1080 }, "id": { "type": "integer", "example": 1 }, "image": { "type": "string", "example": "/uploads/heroes/img.jpg" }, "is_active": { "type": "boolean" }, "quality": { "type": "integer", "example": 80 }, "text1": { "type": "string", "example": "Kısa açıklama" }, "text2": { "type": "string", "example": "İkinci metin" }, "text4": { "type": "string", "example": "Yardımcı metin" }, "text5": { "type": "string", "example": "Ek metin" }, "title": { "type": "string", "example": "Hero Başlık" }, "updated_at": { "type": "string" }, "width": { "type": "integer", "example": 1920 } } }, "controllers.LoginPayload": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string" }, "password": { "type": "string" } } }, "controllers.PostListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/controllers.PostResponse" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "controllers.PostPayload": { "type": "object", "required": [ "title" ], "properties": { "category_ids": { "type": "array", "items": { "type": "integer" } }, "content": { "type": "string" }, "images": { "type": "string" }, "slug": { "type": "string" }, "tag_names": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" } } }, "controllers.PostResponse": { "type": "object", "properties": { "categories": { "type": "array", "items": { "$ref": "#/definitions/controllers.CategorySimple" } }, "content": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "integer", "example": 1 }, "images": { "type": "string" }, "slug": { "type": "string", "example": "my-post-title" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.TagSimple" } }, "title": { "type": "string", "example": "My post title" }, "updated_at": { "type": "string" } } }, "controllers.RefreshPayload": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string" } } }, "controllers.RegisterPayload": { "type": "object", "required": [ "email", "password", "username" ], "properties": { "email": { "type": "string" }, "password": { "type": "string", "minLength": 6 }, "username": { "type": "string" } } }, "controllers.SettingListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/controllers.SettingResponse" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "controllers.SettingResponse": { "type": "object", "properties": { "address": { "type": "string", "example": "Adres örneği" }, "b_format": { "type": "string" }, "b_height": { "type": "integer" }, "b_logo": { "type": "string" }, "b_quality": { "type": "integer" }, "b_width": { "type": "integer" }, "copyright": { "type": "string", "example": "© 2026 Example" }, "created_at": { "type": "string" }, "email": { "type": "string", "example": "info@example.com" }, "facebook": { "type": "string", "example": "https://facebook.com/example" }, "id": { "type": "integer", "example": 1 }, "instagram": { "type": "string", "example": "https://instagram.com/example" }, "is_active": { "type": "boolean" }, "linkedin": { "type": "string", "example": "https://linkedin.com/company/example" }, "map_embed": { "type": "string" }, "meta_description": { "type": "string", "example": "Site açıklaması" }, "meta_title": { "type": "string", "example": "Meta Başlık" }, "phone": { "type": "string", "example": " +90 555 555 55 55" }, "pinterest": { "type": "string", "example": "https://pinterest.com/example" }, "slogan": { "type": "string", "example": "En iyi içerik" }, "title": { "type": "string", "example": "Site Başlığı" }, "updated_at": { "type": "string" }, "url": { "type": "string", "example": "https://example.com" }, "w_format": { "type": "string" }, "w_height": { "type": "integer" }, "w_logo": { "type": "string" }, "w_quality": { "type": "integer" }, "w_width": { "description": "image transform / metadata fields (match app/database/models/setting.go)", "type": "integer" }, "whatsapp": { "type": "string", "example": "https://wa.me/90555" }, "x": { "type": "string", "example": "https://x.com/example" } } }, "controllers.TagPayload": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "controllers.TagSimple": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "golang" } } }, "controllers.UserPayload": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "description": "Opsiyonel şifre güncellemesi", "type": "string" }, "username": { "type": "string" } } }, "controllers.UserResponse": { "type": "object", "properties": { "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "id": { "type": "integer" }, "is_admin": { "type": "boolean" }, "username": { "type": "string" } } } }, "securityDefinitions": { "BearerAuth": { "description": "Enter your JWT token (include \"Bearer \" prefix, e.g., \"Bearer \u003ctoken\u003e\")", "type": "apiKey", "name": "Authorization", "in": "header" } } }