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
|
||||
|
||||
Reference in New Issue
Block a user