mazyar/tm_back
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor API documentation and update endpoint tags for clarity

Browse Source 
- Updated README.md to reflect changes in endpoint categories, renaming "Customers-Admin" to "Admin-Customers" and "Companies-Admin" to "Admin-Companies" for consistency.
- Modified health check endpoint tags from "Health" to "Admin-Health" to align with the new naming convention.
- Adjusted Swagger documentation to replace outdated tags and ensure accurate representation of the API structure.
- Enhanced user and customer handler documentation to reflect the new "Admin-Authorization" and "Admin-Users" tags, improving clarity in the API documentation.
This commit is contained in:
n.nakhostin
2025-08-11 18:59:31 +03:30
parent 318f3b7878
commit a1db2a9790
12 changed files with 374 additions and 406 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cmd/web/docs/swagger.yaml
+92 -97
View File
@@ -511,9 +511,6 @@ definitions:
items:
type: string
type: array
company_name:
description: Company customer fields
type: string
contact_person:
allOf:
- $ref: '#/definitions/customer.ContactPersonForm'
@@ -545,6 +542,7 @@ definitions:
phone:
type: string
registration_number:
description: Company customer fields
type: string
tax_id:
type: string
@@ -1148,7 +1146,7 @@ paths:
- BearerAuth: []
summary: List companies with filters and pagination
tags:
- Companies-Admin
- Admin-Companies
post:
consumes:
- application/json
@@ -1196,7 +1194,7 @@ paths:
- BearerAuth: []
summary: Create a new company
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/{id}:
delete:
consumes:
@@ -1231,7 +1229,7 @@ paths:
- BearerAuth: []
summary: Delete company
tags:
- Companies-Admin
- Admin-Companies
get:
consumes:
- application/json
@@ -1270,7 +1268,7 @@ paths:
- BearerAuth: []
summary: Get company by ID
tags:
- Companies-Admin
- Admin-Companies
put:
consumes:
- application/json
@@ -1325,7 +1323,7 @@ paths:
- BearerAuth: []
summary: Update company information
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/{id}/activate:
post:
consumes:
@@ -1360,7 +1358,7 @@ paths:
- BearerAuth: []
summary: Activate company
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/{id}/status:
patch:
consumes:
@@ -1405,7 +1403,7 @@ paths:
- BearerAuth: []
summary: Update company status
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/{id}/suspend:
post:
consumes:
@@ -1450,7 +1448,7 @@ paths:
- BearerAuth: []
summary: Suspend company
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/{id}/tags:
put:
consumes:
@@ -1496,7 +1494,7 @@ paths:
- BearerAuth: []
summary: Update company tags
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/{id}/tags/add:
post:
consumes:
@@ -1541,7 +1539,7 @@ paths:
- BearerAuth: []
summary: Add tags to company
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/{id}/tags/remove:
post:
consumes:
@@ -1586,7 +1584,7 @@ paths:
- BearerAuth: []
summary: Remove tags from company
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/{id}/verification:
patch:
consumes:
@@ -1631,7 +1629,7 @@ paths:
- BearerAuth: []
summary: Update company verification status
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/{id}/verify:
post:
consumes:
@@ -1666,7 +1664,7 @@ paths:
- BearerAuth: []
summary: Verify company
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/industry/{industry}:
get:
consumes:
@@ -1719,7 +1717,7 @@ paths:
- BearerAuth: []
summary: Get companies by industry
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/search:
get:
consumes:
@@ -1817,7 +1815,7 @@ paths:
- BearerAuth: []
summary: Advanced search for companies
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/stats:
get:
consumes:
@@ -1843,7 +1841,7 @@ paths:
- BearerAuth: []
summary: Get company statistics
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/status/{status}:
get:
consumes:
@@ -1902,7 +1900,7 @@ paths:
- BearerAuth: []
summary: Get companies by status
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/companies/type/{type}:
get:
consumes:
@@ -1962,7 +1960,7 @@ paths:
- BearerAuth: []
summary: Get companies by type
tags:
- Companies-Admin
- Admin-Companies
/admin/v1/customers:
get:
consumes:
@@ -2077,7 +2075,7 @@ paths:
- BearerAuth: []
summary: List customers with filters and pagination
tags:
- Customers-Admin
- Admin-Customers
post:
consumes:
- application/json
@@ -2124,7 +2122,7 @@ paths:
- BearerAuth: []
summary: Create a new customer
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/{id}:
delete:
consumes:
@@ -2159,7 +2157,7 @@ paths:
- BearerAuth: []
summary: Delete customer
tags:
- Customers-Admin
- Admin-Customers
get:
consumes:
- application/json
@@ -2198,7 +2196,7 @@ paths:
- BearerAuth: []
summary: Get customer by ID
tags:
- Customers-Admin
- Admin-Customers
put:
consumes:
- application/json
@@ -2252,7 +2250,7 @@ paths:
- BearerAuth: []
summary: Update customer information
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/{id}/activate:
post:
consumes:
@@ -2287,7 +2285,7 @@ paths:
- BearerAuth: []
summary: Activate customer
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/{id}/companies/assign:
post:
consumes:
@@ -2332,7 +2330,7 @@ paths:
- BearerAuth: []
summary: Assign companies to a customer
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/{id}/companies/remove:
post:
consumes:
@@ -2377,7 +2375,7 @@ paths:
- BearerAuth: []
summary: Remove companies from a customer
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/{id}/status:
patch:
consumes:
@@ -2422,7 +2420,7 @@ paths:
- BearerAuth: []
summary: Update customer status
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/{id}/suspend:
post:
consumes:
@@ -2467,7 +2465,7 @@ paths:
- BearerAuth: []
summary: Suspend customer
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/{id}/verification:
patch:
consumes:
@@ -2512,7 +2510,7 @@ paths:
- BearerAuth: []
summary: Update customer verification status
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/{id}/verify:
post:
consumes:
@@ -2547,7 +2545,7 @@ paths:
- BearerAuth: []
summary: Verify customer
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/{id}/with-companies:
get:
consumes:
@@ -2588,7 +2586,7 @@ paths:
- BearerAuth: []
summary: Get customer by ID with companies
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/company/{companyId}:
get:
consumes:
@@ -2634,7 +2632,7 @@ paths:
- BearerAuth: []
summary: Get customers by company ID
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/status/{status}:
get:
consumes:
@@ -2693,7 +2691,7 @@ paths:
- BearerAuth: []
summary: Get customers by status
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/type/{type}:
get:
consumes:
@@ -2751,7 +2749,7 @@ paths:
- BearerAuth: []
summary: Get customers by type
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/customers/with-companies:
get:
consumes:
@@ -2866,7 +2864,7 @@ paths:
- BearerAuth: []
summary: List customers with companies and filters
tags:
- Customers-Admin
- Admin-Customers
/admin/v1/health:
get:
consumes:
@@ -2887,7 +2885,7 @@ paths:
$ref: '#/definitions/main.HealthResponse'
summary: Health check endpoint
tags:
- Health
- Admin-Health
/admin/v1/profile:
get:
consumes:
@@ -2923,7 +2921,7 @@ paths:
- BearerAuth: []
summary: Get authenticated user profile
tags:
- Users
- Admin-Users
put:
consumes:
- application/json
@@ -2974,7 +2972,7 @@ paths:
- BearerAuth: []
summary: Update authenticated user profile
tags:
- Users
- Admin-Users
/admin/v1/profile/change-password:
put:
consumes:
@@ -3018,7 +3016,7 @@ paths:
- BearerAuth: []
summary: Change user password
tags:
- Users
- Admin-Users
/admin/v1/profile/login:
post:
consumes:
@@ -3067,7 +3065,7 @@ paths:
$ref: '#/definitions/response.APIResponse'
summary: Authenticate user login
tags:
- Authorization
- Admin-Authorization
/admin/v1/profile/logout:
delete:
consumes:
@@ -3094,7 +3092,7 @@ paths:
- BearerAuth: []
summary: Logout authenticated user
tags:
- Authorization
- Admin-Authorization
/admin/v1/profile/refresh-token:
post:
consumes:
@@ -3139,7 +3137,7 @@ paths:
$ref: '#/definitions/response.APIResponse'
summary: Refresh access token
tags:
- Authorization
- Admin-Authorization
/admin/v1/profile/reset-password:
post:
consumes:
@@ -3183,7 +3181,7 @@ paths:
$ref: '#/definitions/response.APIResponse'
summary: Initiate password reset process
tags:
- Authorization
- Admin-Authorization
/admin/v1/users:
get:
consumes:
@@ -3254,7 +3252,7 @@ paths:
- BearerAuth: []
summary: List users
tags:
- Users
- Admin-Users
post:
consumes:
- application/json
@@ -3310,7 +3308,7 @@ paths:
- BearerAuth: []
summary: Create new user account
tags:
- Users
- Admin-Users
/admin/v1/users/{id}:
delete:
consumes:
@@ -3353,7 +3351,7 @@ paths:
- BearerAuth: []
summary: Delete user
tags:
- Users
- Admin-Users
get:
consumes:
- application/json
@@ -3400,7 +3398,7 @@ paths:
- BearerAuth: []
summary: Get user by ID
tags:
- Users
- Admin-Users
put:
consumes:
- application/json
@@ -3453,7 +3451,7 @@ paths:
- BearerAuth: []
summary: Update user
tags:
- Users
- Admin-Users
/admin/v1/users/{id}/role:
put:
consumes:
@@ -3502,7 +3500,7 @@ paths:
- BearerAuth: []
summary: Update user role
tags:
- Users
- Admin-Users
/admin/v1/users/{id}/status:
put:
consumes:
@@ -3551,7 +3549,7 @@ paths:
- BearerAuth: []
summary: Update user status
tags:
- Users
- Admin-Users
/admin/v1/users/company/{company_id}:
get:
consumes:
@@ -3604,7 +3602,7 @@ paths:
- BearerAuth: []
summary: Get users by company ID
tags:
- Users
- Admin-Users
/admin/v1/users/role/{role}:
get:
consumes:
@@ -3657,8 +3655,8 @@ paths:
- BearerAuth: []
summary: Get users by role
tags:
- Users
/api/v1/:
- Admin-Users
/api/v1/profile:
get:
consumes:
- application/json
@@ -3691,32 +3689,7 @@ paths:
- BearerAuth: []
summary: Get customer profile
tags:
- Customers-Authorization
/api/v1/logout:
delete:
consumes:
- application/json
description: Logout customer and invalidate access token
produces:
- application/json
responses:
"200":
description: Logout successful
schema:
$ref: '#/definitions/response.APIResponse'
"401":
description: Unauthorized - Invalid or missing token
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Customer logout
tags:
- Customers-Authorization
- Authorization
/api/v1/profile/login:
post:
consumes:
@@ -3760,7 +3733,32 @@ paths:
$ref: '#/definitions/response.APIResponse'
summary: Customer login
tags:
- Customers-Authorization
- Authorization
/api/v1/profile/logout:
delete:
consumes:
- application/json
description: Logout customer and invalidate access token
produces:
- application/json
responses:
"200":
description: Logout successful
schema:
$ref: '#/definitions/response.APIResponse'
"401":
description: Unauthorized - Invalid or missing token
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Customer logout
tags:
- Authorization
/api/v1/profile/refresh-token:
post:
consumes:
@@ -3804,8 +3802,8 @@ paths:
$ref: '#/definitions/response.APIResponse'
summary: Refresh customer access token
tags:
- Customers-Authorization
/api/v1/with-companies:
- Authorization
/api/v1/profile/with-companies:
get:
consumes:
- application/json
@@ -3839,7 +3837,7 @@ paths:
- BearerAuth: []
summary: Get customer profile with companies
tags:
- Customers-Authorization
- Authorization
securityDefinitions:
BearerAuth:
description: 'Type "Bearer" followed by a space and JWT token. Example: "Bearer
@@ -3851,24 +3849,21 @@ swagger: "2.0"
tags:
- description: System health check operations for monitoring application status and
dependencies
name: Health
name: Admin-Health
- description: User authentication and authorization operations including login, logout,
token refresh, and password management for web panel administration
name: Authorization
name: Admin-Authorization
- description: Administrative user management operations including CRUD operations,
role management, status updates, and profile management for web panel administrators
name: Users
name: Admin-Users
- description: Administrative customer management operations for web panel including
CRUD operations, company assignment, verification, status management, and comprehensive
filtering with pagination
name: Customers-Admin
- description: Customer authentication and authorization operations for mobile application
including login, logout, token refresh, and profile access
name: Customers-Authorization
name: Admin-Customers
- description: Administrative company management operations for web panel including
CRUD operations, tag management, verification, status updates, comprehensive search
and filtering, and statistical reporting
name: Companies-Admin
- description: Company-related operations for mobile application including company
lookup, search, and basic information retrieval
name: Companies-Mobile
name: Admin-Companies
- description: Customer authentication and authorization operations for mobile application
including login, logout, token refresh, and profile access
name: Authorization