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

Enhance API Documentation with Example Values for Company Forms

Browse Source 
- Updated the Swagger and YAML documentation to include example values for various fields in the CompanyForm and AddressForm, improving clarity for API consumers.
- Added example values for fields such as name, type, registration number, tax ID, industry, and more, ensuring comprehensive documentation.
- Enhanced the response structure in the Swagger documentation to provide better guidance on expected data formats and values.
- This update aligns with best practices for API documentation, facilitating easier integration and usage for developers.
This commit is contained in:
n.nakhostin
2025-09-08 11:26:11 +03:30
parent ee830f8c1b
commit 617547def8
4 changed files with 175 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cmd/web/docs/docs.go
+60 -28
View File
@@ -5156,19 +5156,24 @@ const docTemplate = `{
"type": "object", "type": "object",
"properties": { "properties": {
"city": { "city": {
"type": "string" "type": "string",
"example": "New York"
}, },
"country": { "country": {
"type": "string" "type": "string",
"example": "US"
}, },
"postal_code": { "postal_code": {
"type": "string" "type": "string",
"example": "10001"
}, },
"state": { "state": {
"type": "string" "type": "string",
"example": "NY"
}, },
"street": { "street": {
"type": "string" "type": "string",
"example": "123 Main St"
} }
} }
}, },
@@ -5184,40 +5189,51 @@ const docTemplate = `{
] ]
}, },
"annual_revenue": { "annual_revenue": {
"type": "number" "type": "number",
"example": 1000000
}, },
"currency": { "currency": {
"type": "string" "type": "string",
"example": "USD"
}, },
"description": { "description": {
"type": "string" "type": "string",
"example": "Opplens is a technology company"
}, },
"email": { "email": {
"type": "string" "type": "string",
"example": "info@opplens.com"
}, },
"employee_count": { "employee_count": {
"description": "Business information", "description": "Business information",
"type": "integer" "type": "integer",
"example": 100
}, },
"founded_year": { "founded_year": {
"type": "integer" "type": "integer",
"example": 2020
}, },
"industry": { "industry": {
"type": "string" "type": "string",
"example": "Technology"
}, },
"language": { "language": {
"description": "Settings", "description": "Settings",
"type": "string" "type": "string",
"example": "en"
}, },
"name": { "name": {
"type": "string" "type": "string",
"example": "Opplens"
}, },
"phone": { "phone": {
"description": "Contact information", "description": "Contact information",
"type": "string" "type": "string",
"example": "+1234567890"
}, },
"registration_number": { "registration_number": {
"type": "string" "type": "string",
"example": "1234567890"
}, },
"tags": { "tags": {
"description": "Tags for categorization and search", "description": "Tags for categorization and search",
@@ -5228,16 +5244,20 @@ const docTemplate = `{
] ]
}, },
"tax_id": { "tax_id": {
"type": "string" "type": "string",
"example": "1234567890"
}, },
"timezone": { "timezone": {
"type": "string" "type": "string",
"example": "UTC"
}, },
"type": { "type": {
"type": "string" "type": "string",
"example": "private"
}, },
"website": { "website": {
"type": "string" "type": "string",
"example": "https://opplens.com"
} }
} }
}, },
@@ -5249,9 +5269,6 @@ const docTemplate = `{
"items": { "items": {
"$ref": "#/definitions/company.CompanyResponse" "$ref": "#/definitions/company.CompanyResponse"
} }
},
"meta": {
"$ref": "#/definitions/response.Meta"
} }
} }
}, },
@@ -5402,31 +5419,46 @@ const docTemplate = `{
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"example": [
"Technology"
]
}, },
"certifications": { "certifications": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"example": [
"Opplens"
]
}, },
"cpv_codes": { "cpv_codes": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"example": [
"1234567890"
]
}, },
"keywords": { "keywords": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"example": [
"Opplens"
]
}, },
"specializations": { "specializations": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"example": [
"Opplens"
]
} }
} }
}, },
cmd/web/docs/swagger.json
+60 -28
View File
@@ -5150,19 +5150,24 @@
"type": "object", "type": "object",
"properties": { "properties": {
"city": { "city": {
"type": "string" "type": "string",
"example": "New York"
}, },
"country": { "country": {
"type": "string" "type": "string",
"example": "US"
}, },
"postal_code": { "postal_code": {
"type": "string" "type": "string",
"example": "10001"
}, },
"state": { "state": {
"type": "string" "type": "string",
"example": "NY"
}, },
"street": { "street": {
"type": "string" "type": "string",
"example": "123 Main St"
} }
} }
}, },
@@ -5178,40 +5183,51 @@
] ]
}, },
"annual_revenue": { "annual_revenue": {
"type": "number" "type": "number",
"example": 1000000
}, },
"currency": { "currency": {
"type": "string" "type": "string",
"example": "USD"
}, },
"description": { "description": {
"type": "string" "type": "string",
"example": "Opplens is a technology company"
}, },
"email": { "email": {
"type": "string" "type": "string",
"example": "info@opplens.com"
}, },
"employee_count": { "employee_count": {
"description": "Business information", "description": "Business information",
"type": "integer" "type": "integer",
"example": 100
}, },
"founded_year": { "founded_year": {
"type": "integer" "type": "integer",
"example": 2020
}, },
"industry": { "industry": {
"type": "string" "type": "string",
"example": "Technology"
}, },
"language": { "language": {
"description": "Settings", "description": "Settings",
"type": "string" "type": "string",
"example": "en"
}, },
"name": { "name": {
"type": "string" "type": "string",
"example": "Opplens"
}, },
"phone": { "phone": {
"description": "Contact information", "description": "Contact information",
"type": "string" "type": "string",
"example": "+1234567890"
}, },
"registration_number": { "registration_number": {
"type": "string" "type": "string",
"example": "1234567890"
}, },
"tags": { "tags": {
"description": "Tags for categorization and search", "description": "Tags for categorization and search",
@@ -5222,16 +5238,20 @@
] ]
}, },
"tax_id": { "tax_id": {
"type": "string" "type": "string",
"example": "1234567890"
}, },
"timezone": { "timezone": {
"type": "string" "type": "string",
"example": "UTC"
}, },
"type": { "type": {
"type": "string" "type": "string",
"example": "private"
}, },
"website": { "website": {
"type": "string" "type": "string",
"example": "https://opplens.com"
} }
} }
}, },
@@ -5243,9 +5263,6 @@
"items": { "items": {
"$ref": "#/definitions/company.CompanyResponse" "$ref": "#/definitions/company.CompanyResponse"
} }
},
"meta": {
"$ref": "#/definitions/response.Meta"
} }
} }
}, },
@@ -5396,31 +5413,46 @@
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"example": [
"Technology"
]
}, },
"certifications": { "certifications": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"example": [
"Opplens"
]
}, },
"cpv_codes": { "cpv_codes": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"example": [
"1234567890"
]
}, },
"keywords": { "keywords": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"example": [
"Opplens"
]
}, },
"specializations": { "specializations": {
"type": "array", "type": "array",
"items": { "items": {
"type": "string" "type": "string"
} },
"example": [
"Opplens"
]
} }
} }
}, },
cmd/web/docs/swagger.yaml
+30 -2
View File
@@ -39,14 +39,19 @@ definitions:
company.AddressForm: company.AddressForm:
properties: properties:
city: city:
example: New York
type: string type: string
country: country:
example: US
type: string type: string
postal_code: postal_code:
example: "10001"
type: string type: string
state: state:
example: NY
type: string type: string
street: street:
example: 123 Main St
type: string type: string
type: object type: object
company.CompanyForm: company.CompanyForm:
@@ -56,41 +61,56 @@ definitions:
- $ref: '#/definitions/company.AddressForm' - $ref: '#/definitions/company.AddressForm'
description: Address information description: Address information
annual_revenue: annual_revenue:
example: 1000000
type: number type: number
currency: currency:
example: USD
type: string type: string
description: description:
example: Opplens is a technology company
type: string type: string
email: email:
example: info@opplens.com
type: string type: string
employee_count: employee_count:
description: Business information description: Business information
example: 100
type: integer type: integer
founded_year: founded_year:
example: 2020
type: integer type: integer
industry: industry:
example: Technology
type: string type: string
language: language:
description: Settings description: Settings
example: en
type: string type: string
name: name:
example: Opplens
type: string type: string
phone: phone:
description: Contact information description: Contact information
example: "+1234567890"
type: string type: string
registration_number: registration_number:
example: "1234567890"
type: string type: string
tags: tags:
allOf: allOf:
- $ref: '#/definitions/company.CompanyTagsForm' - $ref: '#/definitions/company.CompanyTagsForm'
description: Tags for categorization and search description: Tags for categorization and search
tax_id: tax_id:
example: "1234567890"
type: string type: string
timezone: timezone:
example: UTC
type: string type: string
type: type:
example: private
type: string type: string
website: website:
example: https://opplens.com
type: string type: string
type: object type: object
company.CompanyListResponse: company.CompanyListResponse:
@@ -99,8 +119,6 @@ definitions:
items: items:
$ref: '#/definitions/company.CompanyResponse' $ref: '#/definitions/company.CompanyResponse'
type: array type: array
meta:
$ref: '#/definitions/response.Meta'
type: object type: object
company.CompanyProfileResponse: company.CompanyProfileResponse:
properties: properties:
@@ -199,22 +217,32 @@ definitions:
company.CompanyTagsForm: company.CompanyTagsForm:
properties: properties:
categories: categories:
example:
- Technology
items: items:
type: string type: string
type: array type: array
certifications: certifications:
example:
- Opplens
items: items:
type: string type: string
type: array type: array
cpv_codes: cpv_codes:
example:
- "1234567890"
items: items:
type: string type: string
type: array type: array
keywords: keywords:
example:
- Opplens
items: items:
type: string type: string
type: array type: array
specializations: specializations:
example:
- Opplens
items: items:
type: string type: string
type: array type: array
internal/company/form.go
+25 -25
View File
@@ -5,51 +5,51 @@ import "tm/pkg/response"
// CompanyForm represents the form for creating/updating a new company // CompanyForm represents the form for creating/updating a new company
type ( type (
CompanyForm struct { CompanyForm struct {
Name string `json:"name" valid:"required,length(2|200)"` Name string `json:"name" valid:"required,length(2|200)" example:"Opplens"`
Type string `json:"type" valid:"required,in(private|public|government|ngo|startup)"` Type string `json:"type" valid:"required,in(private|public|government|ngo|startup)" example:"private"`
RegistrationNumber string `json:"registration_number" valid:"required,length(5|50)"` RegistrationNumber string `json:"registration_number" valid:"required,length(5|50)" example:"1234567890"`
TaxID string `json:"tax_id" valid:"required,length(5|50)"` TaxID string `json:"tax_id" valid:"required,length(5|50)" example:"1234567890"`
Industry string `json:"industry" valid:"required,length(2|100)"` Industry string `json:"industry" valid:"required,length(2|100)" example:"Technology"`
Description *string `json:"description,omitempty" valid:"optional,length(10|1000)"` Description *string `json:"description,omitempty" valid:"optional,length(10|1000)" example:"Opplens is a technology company"`
Website *string `json:"website,omitempty" valid:"optional,url"` Website *string `json:"website,omitempty" valid:"optional,url" example:"https://opplens.com"`
// Business information // Business information
EmployeeCount *int `json:"employee_count,omitempty" valid:"optional,range(1|100000)"` EmployeeCount *int `json:"employee_count,omitempty" valid:"optional,range(1|100000)" example:"100"`
AnnualRevenue *float64 `json:"annual_revenue,omitempty" valid:"optional,range(0|999999999999)"` AnnualRevenue *float64 `json:"annual_revenue,omitempty" valid:"optional,range(0|999999999999)" example:"1000000"`
FoundedYear *int `json:"founded_year,omitempty" valid:"optional,range(1800|2100)"` FoundedYear *int `json:"founded_year,omitempty" valid:"optional,range(1800|2100)" example:"2020"`
// Address information // Address information
Address *AddressForm `json:"address,omitempty"` Address *AddressForm `json:"address,omitempty"`
// Contact information // Contact information
Phone *string `json:"phone,omitempty" valid:"optional,length(10|20)"` Phone *string `json:"phone,omitempty" valid:"optional,length(10|20)" example:"+1234567890"`
Email *string `json:"email,omitempty" valid:"optional,email"` Email *string `json:"email,omitempty" valid:"optional,email" example:"info@opplens.com"`
// Tags for categorization and search // Tags for categorization and search
Tags *CompanyTagsForm `json:"tags,omitempty"` Tags *CompanyTagsForm `json:"tags,omitempty"`
// Settings // Settings
Language *string `json:"language,omitempty" valid:"optional,in(en|ar|fr|es|de|zh|ja|ko)"` Language *string `json:"language,omitempty" valid:"optional,in(en|ar|fr|es|de|zh|ja|ko)" example:"en"`
Currency *string `json:"currency,omitempty" valid:"optional,in(USD|EUR|GBP|JPY|CAD|AUD|CHF|CNY|INR|BRL)"` Currency *string `json:"currency,omitempty" valid:"optional,in(USD|EUR|GBP|JPY|CAD|AUD|CHF|CNY|INR|BRL)" example:"USD"`
Timezone *string `json:"timezone,omitempty" valid:"optional,length(3|50)"` Timezone *string `json:"timezone,omitempty" valid:"optional,length(3|50)" example:"UTC"`
} }
// AddressForm represents the form for company address // AddressForm represents the form for company address
AddressForm struct { AddressForm struct {
Street string `json:"street" valid:"required,length(5|200)"` Street string `json:"street" valid:"required,length(5|200)" example:"123 Main St"`
City string `json:"city" valid:"required,length(2|100)"` City string `json:"city" valid:"required,length(2|100)" example:"New York"`
State string `json:"state" valid:"required,length(2|100)"` State string `json:"state" valid:"required,length(2|100)" example:"NY"`
PostalCode string `json:"postal_code" valid:"required,length(3|20)"` PostalCode string `json:"postal_code" valid:"required,length(3|20)" example:"10001"`
Country string `json:"country" valid:"required,length(2|100)"` Country string `json:"country" valid:"required,length(2|100)" example:"US"`
} }
// CompanyTagsForm represents the form for company tags // CompanyTagsForm represents the form for company tags
CompanyTagsForm struct { CompanyTagsForm struct {
CPVCodes []string `json:"cpv_codes,omitempty" valid:"optional"` CPVCodes []string `json:"cpv_codes,omitempty" valid:"optional" example:"1234567890"`
Categories []string `json:"categories,omitempty" valid:"optional"` Categories []string `json:"categories,omitempty" valid:"optional" example:"Technology"`
Keywords []string `json:"keywords,omitempty" valid:"optional"` Keywords []string `json:"keywords,omitempty" valid:"optional" example:"Opplens"`
Specializations []string `json:"specializations,omitempty" valid:"optional"` Specializations []string `json:"specializations,omitempty" valid:"optional" example:"Opplens"`
Certifications []string `json:"certifications,omitempty" valid:"optional"` Certifications []string `json:"certifications,omitempty" valid:"optional" example:"Opplens"`
} }
) )