Update Swagger Documentation for CMS Endpoints

- Refactored API paths to replace "companies" with "cms" for better alignment with CMS management functionality.
- Updated descriptions, parameters, and responses for CMS-related endpoints to reflect new functionality, including search, create, retrieve, update, and delete operations.
- Enhanced the Swagger documentation to include detailed definitions for CMS entities, forms, and responses, ensuring comprehensive API specifications.
- Improved consistency in naming conventions and descriptions across the CMS API endpoints.
This commit is contained in:
n.nakhostin
2025-11-04 11:15:48 +03:30
parent 9a444a1e7d
commit cdd636485d
3 changed files with 2102 additions and 18 deletions
+791 -6
View File
@@ -16,6 +16,342 @@
"version": "1.0.0"
},
"paths": {
"/admin/v1/cms": {
"get": {
"description": "Search CMS entries with filters and pagination (admin only)",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Admin-CMS"
],
"summary": "Search CMS entries",
"parameters": [
{
"type": "string",
"description": "Search query",
"name": "q",
"in": "query"
},
{
"type": "string",
"description": "CMS key filter",
"name": "key",
"in": "query"
},
{
"maximum": 100,
"minimum": 1,
"type": "integer",
"default": 20,
"description": "Number of CMS entries per page (1-100)",
"name": "limit",
"in": "query"
},
{
"minimum": 0,
"type": "integer",
"default": 0,
"description": "Number of CMS entries to skip for pagination",
"name": "offset",
"in": "query"
},
{
"enum": [
"key",
"created_at",
"updated_at"
],
"type": "string",
"default": "created_at",
"description": "Field to sort by",
"name": "sort_by",
"in": "query"
},
{
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Sort order",
"name": "sort_order",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.APIResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/cms.CMSListResponse"
}
}
}
]
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
}
}
},
"post": {
"description": "Create a new CMS entry for content management (admin only)",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Admin-CMS"
],
"summary": "Create a new CMS entry",
"parameters": [
{
"description": "CMS information",
"name": "cms",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/cms.CMSForm"
}
}
],
"responses": {
"201": {
"description": "Created",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.APIResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/cms.CMSResponse"
}
}
}
]
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
}
}
}
},
"/admin/v1/cms/{id}": {
"get": {
"description": "Retrieve a CMS entry by its ID for editing (admin only)",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Admin-CMS"
],
"summary": "Get CMS by ID",
"parameters": [
{
"type": "string",
"description": "CMS ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.APIResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/cms.CMSResponse"
}
}
}
]
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
}
}
},
"put": {
"description": "Update an existing CMS entry by its ID (admin only)",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Admin-CMS"
],
"summary": "Update CMS entry",
"parameters": [
{
"type": "string",
"description": "CMS ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "Updated CMS information",
"name": "cms",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/cms.CMSForm"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.APIResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/cms.CMSResponse"
}
}
}
]
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
},
"409": {
"description": "Conflict",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
}
}
},
"delete": {
"description": "Delete a CMS entry by its ID (admin only)",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Admin-CMS"
],
"summary": "Delete CMS entry",
"parameters": [
{
"type": "string",
"description": "CMS ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
}
}
}
},
"/admin/v1/companies": {
"get": {
"security": [
@@ -1045,7 +1381,7 @@
"application/json"
],
"tags": [
"contacts"
"Admin-Contacts"
],
"summary": "Search contacts",
"parameters": [
@@ -1166,7 +1502,7 @@
"application/json"
],
"tags": [
"contacts"
"Admin-Contacts"
],
"summary": "Get contact statistics",
"responses": {
@@ -1207,7 +1543,7 @@
"application/json"
],
"tags": [
"contacts"
"Admin-Contacts"
],
"summary": "Get contact by ID",
"parameters": [
@@ -1267,7 +1603,7 @@
"application/json"
],
"tags": [
"contacts"
"Admin-Contacts"
],
"summary": "Delete contact",
"parameters": [
@@ -1317,7 +1653,7 @@
"application/json"
],
"tags": [
"contacts"
"Admin-Contacts"
],
"summary": "Update contact status",
"parameters": [
@@ -4970,6 +5306,62 @@
}
}
},
"/api/v1/cms/{key}": {
"get": {
"description": "Retrieve CMS content for public display by its key",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"CMS"
],
"summary": "Get CMS content by key",
"parameters": [
{
"type": "string",
"description": "CMS key",
"name": "key",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"allOf": [
{
"$ref": "#/definitions/response.APIResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/cms.CMSResponse"
}
}
}
]
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/response.APIResponse"
}
}
}
}
},
"/api/v1/companies": {
"get": {
"security": [
@@ -5032,7 +5424,7 @@
"application/json"
],
"tags": [
"contacts"
"Contacts"
],
"summary": "Create a new contact message",
"parameters": [
@@ -7332,6 +7724,383 @@
}
}
},
"cms.CMSForm": {
"type": "object",
"properties": {
"advantages": {
"$ref": "#/definitions/cms.cardSectionForm"
},
"challenges": {
"$ref": "#/definitions/cms.cardSectionForm"
},
"chart": {
"$ref": "#/definitions/cms.chartSectionForm"
},
"contact": {
"$ref": "#/definitions/cms.contactSectionForm"
},
"features": {
"$ref": "#/definitions/cms.cardSectionForm"
},
"footer": {
"$ref": "#/definitions/cms.footerSectionForm"
},
"hero": {
"$ref": "#/definitions/cms.heroSectionForm"
},
"key": {
"type": "string",
"example": "SW-001"
}
}
},
"cms.CMSListResponse": {
"type": "object",
"properties": {
"cms": {
"type": "array",
"items": {
"$ref": "#/definitions/cms.CMSResponse"
}
}
}
},
"cms.CMSResponse": {
"type": "object",
"properties": {
"advantages": {
"$ref": "#/definitions/cms.cardSection"
},
"challenges": {
"$ref": "#/definitions/cms.cardSection"
},
"chart": {
"$ref": "#/definitions/cms.chartSection"
},
"contact": {
"$ref": "#/definitions/cms.contactSection"
},
"created_at": {
"type": "integer"
},
"features": {
"$ref": "#/definitions/cms.cardSection"
},
"footer": {
"$ref": "#/definitions/cms.footerSection"
},
"hero": {
"$ref": "#/definitions/cms.heroSection"
},
"id": {
"type": "string"
},
"key": {
"type": "string"
},
"updated_at": {
"type": "integer"
}
}
},
"cms.card": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"icon": {
"type": "string"
},
"title": {
"type": "string"
}
}
},
"cms.cardForm": {
"type": "object",
"properties": {
"description": {
"type": "string",
"example": "Card Description"
},
"icon": {
"type": "string",
"example": "https://example.com/icon.png"
},
"title": {
"type": "string",
"example": "Card Title"
}
}
},
"cms.cardSection": {
"type": "object",
"properties": {
"cards": {
"type": "array",
"items": {
"$ref": "#/definitions/cms.card"
}
},
"description": {
"type": "string"
},
"title": {
"type": "string"
}
}
},
"cms.cardSectionForm": {
"type": "object",
"properties": {
"cards": {
"type": "array",
"items": {
"$ref": "#/definitions/cms.cardForm"
}
},
"description": {
"type": "string",
"example": "Card Description"
},
"title": {
"type": "string",
"example": "Card Title"
}
}
},
"cms.chartPoint": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "integer"
}
}
},
"cms.chartPointForm": {
"type": "object",
"properties": {
"key": {
"type": "string",
"example": "Key"
},
"value": {
"type": "integer",
"example": 1000000
}
}
},
"cms.chartSection": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/cms.chartPoint"
}
},
"missedAmount": {
"type": "string"
},
"title": {
"type": "string"
}
}
},
"cms.chartSectionForm": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/cms.chartPointForm"
}
},
"missed_amount": {
"type": "string",
"example": "Missed Amount"
},
"title": {
"type": "string",
"example": "Chart Title"
}
}
},
"cms.contactSection": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"$ref": "#/definitions/cms.formField"
}
},
"submitButtonText": {
"type": "string"
},
"title": {
"type": "string"
}
}
},
"cms.contactSectionForm": {
"type": "object",
"properties": {
"description": {
"type": "string",
"example": "Contact Description"
},
"fields": {
"type": "array",
"items": {
"$ref": "#/definitions/cms.formFieldForm"
}
},
"submit_button_text": {
"type": "string",
"example": "Submit Button Text"
},
"title": {
"type": "string",
"example": "Contact Title"
}
}
},
"cms.footerSection": {
"type": "object",
"properties": {
"copyright": {
"type": "string"
},
"email": {
"type": "string"
},
"location": {
"type": "string"
},
"phone": {
"type": "string"
},
"tagline": {
"type": "string"
}
}
},
"cms.footerSectionForm": {
"type": "object",
"properties": {
"copyright": {
"type": "string",
"example": "Copyright"
},
"email": {
"type": "string",
"example": "info@example.com"
},
"location": {
"type": "string",
"example": "Location"
},
"phone": {
"type": "string",
"example": "+1234567890"
},
"tagline": {
"type": "string",
"example": "Tagline"
}
}
},
"cms.formField": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"name": {
"type": "string"
},
"placeholder": {
"type": "string"
},
"required": {
"type": "boolean"
}
}
},
"cms.formFieldForm": {
"type": "object",
"properties": {
"label": {
"type": "string",
"example": "Label"
},
"name": {
"type": "string",
"example": "Name"
},
"placeholder": {
"type": "string",
"example": "Placeholder"
},
"required": {
"type": "boolean",
"example": true
}
}
},
"cms.heroSection": {
"type": "object",
"properties": {
"buttonLink": {
"type": "string"
},
"buttonText": {
"type": "string"
},
"description": {
"type": "string"
},
"gifFile": {
"type": "string"
},
"title": {
"type": "string"
}
}
},
"cms.heroSectionForm": {
"type": "object",
"properties": {
"button_link": {
"type": "string",
"example": "https://example.com"
},
"button_text": {
"type": "string",
"example": "Button Text"
},
"description": {
"type": "string",
"example": "Hero Description"
},
"gif_file": {
"type": "string",
"example": "https://example.com/gif.gif"
},
"title": {
"type": "string",
"example": "Hero Title"
}
}
},
"company.Address": {
"type": "object",
"properties": {
@@ -9421,6 +10190,14 @@
"description": "Administrative notification management operations for web panel including CRUD operations, bulk notifications, queue management, and comprehensive filtering with pagination",
"name": "Admin-Notification"
},
{
"description": "Administrative contact management operations for web panel including CRUD operations, search, statistics, and comprehensive filtering with pagination",
"name": "Admin-Contacts"
},
{
"description": "Administrative CMS management operations for web panel including CRUD operations, search, statistics, and comprehensive filtering with pagination",
"name": "Admin-CMS"
},
{
"description": "Customer authentication and authorization operations for mobile application including login, logout, token refresh, and profile access",
"name": "Authorization"
@@ -9452,6 +10229,14 @@
{
"description": "Public notification management operations for mobile application including notification listing and detailed notification information",
"name": "Notification"
},
{
"description": "Public contact management operations for mobile application including contact submission and contact listing",
"name": "Contacts"
},
{
"description": "Public CMS management operations for mobile application including CMS listing and detailed CMS information",
"name": "CMS"
}
]
}