Enhance API Documentation with Example Values for Company Forms
- 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
+60
-28
@@ -5156,19 +5156,24 @@ const docTemplate = `{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"city": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "New York"
|
||||
},
|
||||
"country": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "US"
|
||||
},
|
||||
"postal_code": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "10001"
|
||||
},
|
||||
"state": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "NY"
|
||||
},
|
||||
"street": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "123 Main St"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -5184,40 +5189,51 @@ const docTemplate = `{
|
||||
]
|
||||
},
|
||||
"annual_revenue": {
|
||||
"type": "number"
|
||||
"type": "number",
|
||||
"example": 1000000
|
||||
},
|
||||
"currency": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "USD"
|
||||
},
|
||||
"description": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "Opplens is a technology company"
|
||||
},
|
||||
"email": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "info@opplens.com"
|
||||
},
|
||||
"employee_count": {
|
||||
"description": "Business information",
|
||||
"type": "integer"
|
||||
"type": "integer",
|
||||
"example": 100
|
||||
},
|
||||
"founded_year": {
|
||||
"type": "integer"
|
||||
"type": "integer",
|
||||
"example": 2020
|
||||
},
|
||||
"industry": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "Technology"
|
||||
},
|
||||
"language": {
|
||||
"description": "Settings",
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "en"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "Opplens"
|
||||
},
|
||||
"phone": {
|
||||
"description": "Contact information",
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "+1234567890"
|
||||
},
|
||||
"registration_number": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "1234567890"
|
||||
},
|
||||
"tags": {
|
||||
"description": "Tags for categorization and search",
|
||||
@@ -5228,16 +5244,20 @@ const docTemplate = `{
|
||||
]
|
||||
},
|
||||
"tax_id": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "1234567890"
|
||||
},
|
||||
"timezone": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "UTC"
|
||||
},
|
||||
"type": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "private"
|
||||
},
|
||||
"website": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "https://opplens.com"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -5249,9 +5269,6 @@ const docTemplate = `{
|
||||
"items": {
|
||||
"$ref": "#/definitions/company.CompanyResponse"
|
||||
}
|
||||
},
|
||||
"meta": {
|
||||
"$ref": "#/definitions/response.Meta"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -5402,31 +5419,46 @@ const docTemplate = `{
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"example": [
|
||||
"Technology"
|
||||
]
|
||||
},
|
||||
"certifications": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"example": [
|
||||
"Opplens"
|
||||
]
|
||||
},
|
||||
"cpv_codes": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"example": [
|
||||
"1234567890"
|
||||
]
|
||||
},
|
||||
"keywords": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"example": [
|
||||
"Opplens"
|
||||
]
|
||||
},
|
||||
"specializations": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"example": [
|
||||
"Opplens"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
+60
-28
@@ -5150,19 +5150,24 @@
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"city": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "New York"
|
||||
},
|
||||
"country": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "US"
|
||||
},
|
||||
"postal_code": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "10001"
|
||||
},
|
||||
"state": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "NY"
|
||||
},
|
||||
"street": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "123 Main St"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -5178,40 +5183,51 @@
|
||||
]
|
||||
},
|
||||
"annual_revenue": {
|
||||
"type": "number"
|
||||
"type": "number",
|
||||
"example": 1000000
|
||||
},
|
||||
"currency": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "USD"
|
||||
},
|
||||
"description": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "Opplens is a technology company"
|
||||
},
|
||||
"email": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "info@opplens.com"
|
||||
},
|
||||
"employee_count": {
|
||||
"description": "Business information",
|
||||
"type": "integer"
|
||||
"type": "integer",
|
||||
"example": 100
|
||||
},
|
||||
"founded_year": {
|
||||
"type": "integer"
|
||||
"type": "integer",
|
||||
"example": 2020
|
||||
},
|
||||
"industry": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "Technology"
|
||||
},
|
||||
"language": {
|
||||
"description": "Settings",
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "en"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "Opplens"
|
||||
},
|
||||
"phone": {
|
||||
"description": "Contact information",
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "+1234567890"
|
||||
},
|
||||
"registration_number": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "1234567890"
|
||||
},
|
||||
"tags": {
|
||||
"description": "Tags for categorization and search",
|
||||
@@ -5222,16 +5238,20 @@
|
||||
]
|
||||
},
|
||||
"tax_id": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "1234567890"
|
||||
},
|
||||
"timezone": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "UTC"
|
||||
},
|
||||
"type": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "private"
|
||||
},
|
||||
"website": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"example": "https://opplens.com"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -5243,9 +5263,6 @@
|
||||
"items": {
|
||||
"$ref": "#/definitions/company.CompanyResponse"
|
||||
}
|
||||
},
|
||||
"meta": {
|
||||
"$ref": "#/definitions/response.Meta"
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -5396,31 +5413,46 @@
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"example": [
|
||||
"Technology"
|
||||
]
|
||||
},
|
||||
"certifications": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"example": [
|
||||
"Opplens"
|
||||
]
|
||||
},
|
||||
"cpv_codes": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"example": [
|
||||
"1234567890"
|
||||
]
|
||||
},
|
||||
"keywords": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"example": [
|
||||
"Opplens"
|
||||
]
|
||||
},
|
||||
"specializations": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"example": [
|
||||
"Opplens"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
@@ -39,14 +39,19 @@ definitions:
|
||||
company.AddressForm:
|
||||
properties:
|
||||
city:
|
||||
example: New York
|
||||
type: string
|
||||
country:
|
||||
example: US
|
||||
type: string
|
||||
postal_code:
|
||||
example: "10001"
|
||||
type: string
|
||||
state:
|
||||
example: NY
|
||||
type: string
|
||||
street:
|
||||
example: 123 Main St
|
||||
type: string
|
||||
type: object
|
||||
company.CompanyForm:
|
||||
@@ -56,41 +61,56 @@ definitions:
|
||||
- $ref: '#/definitions/company.AddressForm'
|
||||
description: Address information
|
||||
annual_revenue:
|
||||
example: 1000000
|
||||
type: number
|
||||
currency:
|
||||
example: USD
|
||||
type: string
|
||||
description:
|
||||
example: Opplens is a technology company
|
||||
type: string
|
||||
email:
|
||||
example: info@opplens.com
|
||||
type: string
|
||||
employee_count:
|
||||
description: Business information
|
||||
example: 100
|
||||
type: integer
|
||||
founded_year:
|
||||
example: 2020
|
||||
type: integer
|
||||
industry:
|
||||
example: Technology
|
||||
type: string
|
||||
language:
|
||||
description: Settings
|
||||
example: en
|
||||
type: string
|
||||
name:
|
||||
example: Opplens
|
||||
type: string
|
||||
phone:
|
||||
description: Contact information
|
||||
example: "+1234567890"
|
||||
type: string
|
||||
registration_number:
|
||||
example: "1234567890"
|
||||
type: string
|
||||
tags:
|
||||
allOf:
|
||||
- $ref: '#/definitions/company.CompanyTagsForm'
|
||||
description: Tags for categorization and search
|
||||
tax_id:
|
||||
example: "1234567890"
|
||||
type: string
|
||||
timezone:
|
||||
example: UTC
|
||||
type: string
|
||||
type:
|
||||
example: private
|
||||
type: string
|
||||
website:
|
||||
example: https://opplens.com
|
||||
type: string
|
||||
type: object
|
||||
company.CompanyListResponse:
|
||||
@@ -99,8 +119,6 @@ definitions:
|
||||
items:
|
||||
$ref: '#/definitions/company.CompanyResponse'
|
||||
type: array
|
||||
meta:
|
||||
$ref: '#/definitions/response.Meta'
|
||||
type: object
|
||||
company.CompanyProfileResponse:
|
||||
properties:
|
||||
@@ -199,22 +217,32 @@ definitions:
|
||||
company.CompanyTagsForm:
|
||||
properties:
|
||||
categories:
|
||||
example:
|
||||
- Technology
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
certifications:
|
||||
example:
|
||||
- Opplens
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
cpv_codes:
|
||||
example:
|
||||
- "1234567890"
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
keywords:
|
||||
example:
|
||||
- Opplens
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
specializations:
|
||||
example:
|
||||
- Opplens
|
||||
items:
|
||||
type: string
|
||||
type: array
|
||||
|
||||
+25
-25
@@ -5,51 +5,51 @@ import "tm/pkg/response"
|
||||
// CompanyForm represents the form for creating/updating a new company
|
||||
type (
|
||||
CompanyForm struct {
|
||||
Name string `json:"name" valid:"required,length(2|200)"`
|
||||
Type string `json:"type" valid:"required,in(private|public|government|ngo|startup)"`
|
||||
RegistrationNumber string `json:"registration_number" valid:"required,length(5|50)"`
|
||||
TaxID string `json:"tax_id" valid:"required,length(5|50)"`
|
||||
Industry string `json:"industry" valid:"required,length(2|100)"`
|
||||
Description *string `json:"description,omitempty" valid:"optional,length(10|1000)"`
|
||||
Website *string `json:"website,omitempty" valid:"optional,url"`
|
||||
Name string `json:"name" valid:"required,length(2|200)" example:"Opplens"`
|
||||
Type string `json:"type" valid:"required,in(private|public|government|ngo|startup)" example:"private"`
|
||||
RegistrationNumber string `json:"registration_number" valid:"required,length(5|50)" example:"1234567890"`
|
||||
TaxID string `json:"tax_id" valid:"required,length(5|50)" example:"1234567890"`
|
||||
Industry string `json:"industry" valid:"required,length(2|100)" example:"Technology"`
|
||||
Description *string `json:"description,omitempty" valid:"optional,length(10|1000)" example:"Opplens is a technology company"`
|
||||
Website *string `json:"website,omitempty" valid:"optional,url" example:"https://opplens.com"`
|
||||
|
||||
// Business information
|
||||
EmployeeCount *int `json:"employee_count,omitempty" valid:"optional,range(1|100000)"`
|
||||
AnnualRevenue *float64 `json:"annual_revenue,omitempty" valid:"optional,range(0|999999999999)"`
|
||||
FoundedYear *int `json:"founded_year,omitempty" valid:"optional,range(1800|2100)"`
|
||||
EmployeeCount *int `json:"employee_count,omitempty" valid:"optional,range(1|100000)" example:"100"`
|
||||
AnnualRevenue *float64 `json:"annual_revenue,omitempty" valid:"optional,range(0|999999999999)" example:"1000000"`
|
||||
FoundedYear *int `json:"founded_year,omitempty" valid:"optional,range(1800|2100)" example:"2020"`
|
||||
|
||||
// Address information
|
||||
Address *AddressForm `json:"address,omitempty"`
|
||||
|
||||
// Contact information
|
||||
Phone *string `json:"phone,omitempty" valid:"optional,length(10|20)"`
|
||||
Email *string `json:"email,omitempty" valid:"optional,email"`
|
||||
Phone *string `json:"phone,omitempty" valid:"optional,length(10|20)" example:"+1234567890"`
|
||||
Email *string `json:"email,omitempty" valid:"optional,email" example:"info@opplens.com"`
|
||||
|
||||
// Tags for categorization and search
|
||||
Tags *CompanyTagsForm `json:"tags,omitempty"`
|
||||
|
||||
// Settings
|
||||
Language *string `json:"language,omitempty" valid:"optional,in(en|ar|fr|es|de|zh|ja|ko)"`
|
||||
Currency *string `json:"currency,omitempty" valid:"optional,in(USD|EUR|GBP|JPY|CAD|AUD|CHF|CNY|INR|BRL)"`
|
||||
Timezone *string `json:"timezone,omitempty" valid:"optional,length(3|50)"`
|
||||
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)" example:"USD"`
|
||||
Timezone *string `json:"timezone,omitempty" valid:"optional,length(3|50)" example:"UTC"`
|
||||
}
|
||||
|
||||
// AddressForm represents the form for company address
|
||||
AddressForm struct {
|
||||
Street string `json:"street" valid:"required,length(5|200)"`
|
||||
City string `json:"city" valid:"required,length(2|100)"`
|
||||
State string `json:"state" valid:"required,length(2|100)"`
|
||||
PostalCode string `json:"postal_code" valid:"required,length(3|20)"`
|
||||
Country string `json:"country" valid:"required,length(2|100)"`
|
||||
Street string `json:"street" valid:"required,length(5|200)" example:"123 Main St"`
|
||||
City string `json:"city" valid:"required,length(2|100)" example:"New York"`
|
||||
State string `json:"state" valid:"required,length(2|100)" example:"NY"`
|
||||
PostalCode string `json:"postal_code" valid:"required,length(3|20)" example:"10001"`
|
||||
Country string `json:"country" valid:"required,length(2|100)" example:"US"`
|
||||
}
|
||||
|
||||
// CompanyTagsForm represents the form for company tags
|
||||
CompanyTagsForm struct {
|
||||
CPVCodes []string `json:"cpv_codes,omitempty" valid:"optional"`
|
||||
Categories []string `json:"categories,omitempty" valid:"optional"`
|
||||
Keywords []string `json:"keywords,omitempty" valid:"optional"`
|
||||
Specializations []string `json:"specializations,omitempty" valid:"optional"`
|
||||
Certifications []string `json:"certifications,omitempty" valid:"optional"`
|
||||
CPVCodes []string `json:"cpv_codes,omitempty" valid:"optional" example:"1234567890"`
|
||||
Categories []string `json:"categories,omitempty" valid:"optional" example:"Technology"`
|
||||
Keywords []string `json:"keywords,omitempty" valid:"optional" example:"Opplens"`
|
||||
Specializations []string `json:"specializations,omitempty" valid:"optional" example:"Opplens"`
|
||||
Certifications []string `json:"certifications,omitempty" valid:"optional" example:"Opplens"`
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user