feat: Update swagger to openapi 3.0.4, update request payloads with examples (#11374)

swagger/definitions/request/portal/article_create_update_payload.yml

@@ -1,34 +1,51 @@
 type: object
 properties:
-  content:
+  title:
     type: string
-    description: The text content.
-  meta:
-    type: object
-    description: Use for search
-    example: { tags: ['article_name'],  title: 'article title', description: 'article description' }
+    description: The title of the article
+    example: 'Article Title'
+  slug:
+    type: string
+    description: The slug of the article
+    example: 'article-title'
   position:
     type: integer
     description: article position in category
-  status:
-    type: integer
-    example: ['draft', 'published', 'archived']
-  title:
+    example: 1
+  content:
     type: string
-  slug:
+    description: The text content.
+    example: 'This is the content of the article'
+  description:
     type: string
-  views:
-    type: integer
-  portal_id:
-    type: integer
-  account_id:
-    type: integer
-  author_id:
-    type: integer
+    description: The description of the article
+    example: 'This is the description of the article'
   category_id:
     type: integer
-  folder_id:
+    description: The category id of the article
+    example: 1
+  author_id:
     type: integer
+    description: The author agent id of the article
+    example: 1
   associated_article_id:
     type: integer
     description: To associate similar articles to each other, e.g to provide the link for the reference.
+    example: 2
+  status:
+    type: integer
+    description: The status of the article. 0 for draft, 1 for published, 2 for archived
+    example: 1
+  locale:
+    type: string
+    description: The locale of the article
+    example: 'en'
+  meta:
+    type: object
+    description: Use for search
+    example:
+      {
+        tags: ['article_name'],
+        title: 'article title',
+        description: 'article description',
+      }

swagger/definitions/request/portal/category_create_update_payload.yml

@@ -1,28 +1,34 @@
 type: object
 properties:
-  description:
-    type: string
-    description: Category description
-  locale:
-    type: string
-    description: Category locale
-    example: en/es
   name:
     type: string
-    description: Category name
-  slug:
+    description: The name of the category
+    example: 'Category Name'
+  description:
     type: string
-    description: Category slug
+    description: A description for the category
+    example: 'Category description'
   position:
     type: integer
     description: Category position in the portal list to sort
-  portal_id:
-    type: integer
-  account_id:
-    type: integer
-  associated_category_id:
-    type: integer
-    description: To associate similar categories to each other, e.g same category of product documentation in different languages
+    example: 1
+  slug:
+    type: string
+    description: The category slug used in the URL
+    example: 'category-name'
+  locale:
+    type: string
+    description: The locale of the category
+    example: en
+  icon:
+    type: string
+    description: The icon of the category as a string (emoji)
+    example: '📚'
   parent_category_id:
     type: integer
     description: To define parent category, e.g product documentation has multiple level features in sales category or in engineering category.
+    example: 1
+  associated_category_id:
+    type: integer
+    description: To associate similar categories to each other, e.g same category of product documentation in different languages
+    example: 2

swagger/definitions/request/portal/portal_create_update_payload.yml

@@ -1,20 +1,13 @@
 type: object
 properties:
-  archived:
-    type: boolean
-    description: Status to check if portal is live
   color:
     type: string
-    description: Header color for help-center
-    example: add color HEX string, "#fffff"
-  config:
-    type: object
-    description: Configuration about supporting locales
-    example: { allowed_locales: ['en', 'es'], default_locale: 'en' }
+    description: Header color for help-center in hex format
+    example: '#FFFFFF'
   custom_domain:
     type: string
-    description: Custom domain to  display help center.
-    example: https://chatwoot.help/.
+    description: Custom domain to display help center.
+    example: chatwoot.help
   header_text:
     type: string
     description: Help center header
@@ -26,11 +19,20 @@ properties:
   name:
     type: string
     description: Name for the portal
-  slug:
-    type: string
-    description: Slug for the portal to display in link
+    example: Handbook
   page_title:
     type: string
     description: Page title for the portal
-  account_id:
-    type: integer
+    example: Handbook
+  slug:
+    type: string
+    description: Slug for the portal to display in link
+    example: handbook
+  archived:
+    type: boolean
+    description: Status to check if portal is live
+    example: false
+  config:
+    type: object
+    description: Configuration about supporting locales
+    example: { allowed_locales: ['en', 'es'], default_locale: 'en' }