From 617547def8dfde7d982d38b65a7e1efef41fa7c5 Mon Sep 17 00:00:00 2001 From: "n.nakhostin" Date: Mon, 8 Sep 2025 11:26:11 +0330 Subject: [PATCH] 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. --- cmd/web/docs/docs.go | 88 ++++++++++++++++++++++++++------------- cmd/web/docs/swagger.json | 88 ++++++++++++++++++++++++++------------- cmd/web/docs/swagger.yaml | 32 +++++++++++++- internal/company/form.go | 50 +++++++++++----------- 4 files changed, 175 insertions(+), 83 deletions(-) diff --git a/cmd/web/docs/docs.go b/cmd/web/docs/docs.go index edc6090..56538b5 100644 --- a/cmd/web/docs/docs.go +++ b/cmd/web/docs/docs.go @@ -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" + ] } } }, diff --git a/cmd/web/docs/swagger.json b/cmd/web/docs/swagger.json index c8e9ac1..e4ef130 100644 --- a/cmd/web/docs/swagger.json +++ b/cmd/web/docs/swagger.json @@ -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" + ] } } }, diff --git a/cmd/web/docs/swagger.yaml b/cmd/web/docs/swagger.yaml index d760aec..80d87c8 100644 --- a/cmd/web/docs/swagger.yaml +++ b/cmd/web/docs/swagger.yaml @@ -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 diff --git a/internal/company/form.go b/internal/company/form.go index 176850a..1565cf5 100644 --- a/internal/company/form.go +++ b/internal/company/form.go @@ -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"` } )