feat: replaced HTML formatting with markdown as new versions of swagger wrapping HTML into code that looks weird, and added documentation for customisations (#1093)

vsamofal · web-flow · commit 2d71292fb1e5 · 2025-08-21T14:46:25.000+02:00
diff --git a/README.md b/README.md
@@ -680,6 +680,50 @@ There is also some syntax sugar for this, and you can use only one decorator `@P
   }
 ```
 
+It is also possible to customize a swagger UI completely or partially, by following the default implementation and creating your own version of PaginatedSwaggerDocs decorator
+
+Let's say you want some custom appearance for SortBy, you need to create a decorator for it
+
+```typescript
+export function CustomSortBy(paginationConfig: PaginateConfig<any>) {
+  return ApiQuery({
+    name: 'sortBy',
+    isArray: true,
+    description: `My custom sort by description`,
+    required: false,
+    type: 'string',
+  })
+}
+```
+
+Now you can create your version of the whole docs decorator and use it
+
+```typescript
+
+const CustomApiPaginationQuery = (paginationConfig: PaginateConfig<any>) => {
+  return applyDecorators(
+    ...[
+      Page(),
+      Limit(paginationConfig),
+      Where(paginationConfig),
+      CustomSortBy(paginationConfig),
+      Search(paginationConfig),
+      SearchBy(paginationConfig),
+      Select(paginationConfig),
+    ].filter((v): v is MethodDecorator => v !== undefined)
+  )
+}
+
+function CustomPaginatedSwaggerDocs<DTO extends Type<unknown>>(dto: DTO, paginatedConfig: PaginateConfig<any>) {
+  return applyDecorators(ApiOkPaginatedResponse(dto, paginatedConfig), CustomApiPaginationQuery(paginatedConfig))
+}
+
+```
+
+You can use CustomPaginatedSwaggerDocs instead of default PaginatedSwaggerDocs
+
+
+
 ## Troubleshooting
 
 The package does not report error reasons in the response bodies. They are instead
diff --git a/src/swagger/api-paginated-query.decorator.ts b/src/swagger/api-paginated-query.decorator.ts
@@ -3,98 +3,128 @@ import { ApiQuery } from '@nestjs/swagger'
 import { FilterComparator } from '../filter'
 import { FilterOperator, FilterSuffix, PaginateConfig } from '../paginate'
 import globalConfig from '../global-config'
+import { isNil } from '../helper'
 
 const DEFAULT_VALUE_KEY = 'Default Value'
 
+const allFilterSuffixes = Object.values(FilterSuffix).map((v) => v.toString())
+
 function p(key: string | 'Format' | 'Example' | 'Default Value' | 'Max Value', value: string) {
-    return `<p>
-             <b>${key}: </b> ${value}
-          </p>`
+    return `
+**${key}:** ${value}
+`
 }
 
 function li(key: string | 'Available Fields', values: string[]) {
-    return `<h4>${key}</h4><ul>${values.map((v) => `<li>${v}</li>`).join('\n')}</ul>`
+    return `**${key}**
+${values.map((v) => `- ${v}`).join('\n\n')}`
 }
 
 export function SortBy(paginationConfig: PaginateConfig<any>) {
+    const sortableColumnNotAvailable =
+        isNil(paginationConfig.sortableColumns) || paginationConfig.sortableColumns.length === 0
+
+    if (isNil(paginationConfig.defaultSortBy) && sortableColumnNotAvailable) {
+        // no sorting allowed or predefined
+        return undefined
+    }
+
     const defaultSortMessage = paginationConfig.defaultSortBy
         ? paginationConfig.defaultSortBy.map(([col, order]) => `${col}:${order}`).join(',')
-        : 'No default sorting specified, the result order is not guaranteed'
+        : 'No default sorting specified, the result order is not guaranteed if not provided'
 
     const sortBy = paginationConfig.sortableColumns.reduce((prev, curr) => {
         return [...prev, `${curr}:ASC`, `${curr}:DESC`]
     }, [])
 
+    const exampleValue = sortableColumnNotAvailable
+        ? 'Allowed sortable columns are not provided, only default sorting will be used'
+        : paginationConfig.sortableColumns
+              .slice(0, 2)
+              .map((col) => `sortBy=${col}:DESC`)
+              .join('&')
+
     return ApiQuery({
         name: 'sortBy',
         isArray: true,
         enum: sortBy,
         description: `Parameter to sort by.
-      <p>To sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting</p>
-      ${p('Format', 'fieldName:DIRECTION')}
-      ${p('Example', 'sortBy=id:DESC&sortBy=createdAt:ASC')}
-      ${p('Default Value', defaultSortMessage)}
-      ${li('Available Fields', paginationConfig.sortableColumns)}
-      `,
+To sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting
+${p('Format', '{fieldName}:{DIRECTION}')}
+${p('Example', exampleValue)}
+${p('Default Value', defaultSortMessage)}
+${li('Available Fields', paginationConfig.sortableColumns)}
+`,
         required: false,
         type: 'string',
     })
 }
 
-function Limit(paginationConfig: PaginateConfig<any>) {
+export function Limit(paginationConfig: PaginateConfig<any>) {
     return ApiQuery({
         name: 'limit',
         description: `Number of records per page.
-      ${p('Example', '20')}
-      ${p(DEFAULT_VALUE_KEY, paginationConfig?.defaultLimit?.toString() || globalConfig.defaultLimit.toString())}
-      ${p('Max Value', paginationConfig.maxLimit?.toString() || globalConfig.defaultMaxLimit.toString())}
 
-      If provided value is greater than max value, max value will be applied.
-      `,
+${p('Example', globalConfig.defaultLimit.toString())}
+
+${p(DEFAULT_VALUE_KEY, paginationConfig?.defaultLimit?.toString() || globalConfig.defaultLimit.toString())}
+
+${p('Max Value', paginationConfig.maxLimit?.toString() || globalConfig.defaultMaxLimit.toString())}
+
+If provided value is greater than max value, max value will be applied.
+`,
         required: false,
         type: 'number',
     })
 }
 
-function Select(paginationConfig: PaginateConfig<any>) {
+export function Select(paginationConfig: PaginateConfig<any>) {
     if (!paginationConfig.select) {
         return
     }
 
     return ApiQuery({
         name: 'select',
         description: `List of fields to select.
-      ${p('Example', paginationConfig.select.slice(0, Math.min(5, paginationConfig.select.length)).join(','))}
-      ${p(
-          DEFAULT_VALUE_KEY,
-          'By default all fields returns. If you want to select only some fields, provide them in query param'
-      )}
-      `,
+${p('Example', paginationConfig.select.slice(0, 5).join(','))}
+${p(
+    DEFAULT_VALUE_KEY,
+    'By default all fields returns. If you want to select only some fields, provide them in query param'
+)}
+`,
         required: false,
         type: 'string',
     })
 }
 
-function Where(paginationConfig: PaginateConfig<any>) {
+export function Where(paginationConfig: PaginateConfig<any>) {
     if (!paginationConfig.filterableColumns) return
 
     const allColumnsDecorators = Object.entries(paginationConfig.filterableColumns)
         .map(([fieldName, filterOperations]) => {
             const operations =
                 filterOperations === true || filterOperations === undefined
-                    ? [
-                          ...Object.values(FilterComparator),
-                          ...Object.values(FilterSuffix),
-                          ...Object.values(FilterOperator),
-                      ]
+                    ? [...Object.values(FilterOperator), ...Object.values(FilterSuffix)]
                     : filterOperations.map((fo) => fo.toString())
 
+            const operationsForExample =
+                operations
+                    .filter((v) => !allFilterSuffixes.includes(v))
+                    .sort()
+                    .slice(0, 2) || []
+
             return ApiQuery({
                 name: `filter.${fieldName}`,
                 description: `Filter by ${fieldName} query param.
-          ${p('Format', `filter.${fieldName}={$not}:OPERATION:VALUE`)}
-          ${p('Example', `filter.${fieldName}=$not:$like:John Doe&filter.${fieldName}=like:John`)}
-          ${li('Available Operations', operations)}`,
+${p('Format', `filter.${fieldName}={$not}:OPERATION:VALUE`)}
+
+${p(
+    'Example',
+    operationsForExample.length === 0
+        ? 'No filtering allowed'
+        : operationsForExample.map((v) => `filter.${fieldName}=${v}:John Doe`).join('&')
+)}
+${li('Available Operations', [...operations, ...Object.values(FilterComparator)])}`,
                 required: false,
                 type: 'string',
                 isArray: true,
@@ -105,45 +135,45 @@ function Where(paginationConfig: PaginateConfig<any>) {
     return applyDecorators(...allColumnsDecorators)
 }
 
-function Page() {
+export function Page() {
     return ApiQuery({
         name: 'page',
-        description: `Page number to retrieve.If you provide invalid value the default page number will applied
-        ${p('Example', '1')}
-        ${p(DEFAULT_VALUE_KEY, '1')}
-        `,
+        description: `Page number to retrieve. If you provide invalid value the default page number will applied
+${p('Example', '1')}
+${p(DEFAULT_VALUE_KEY, '1')}
+`,
         required: false,
         type: 'number',
     })
 }
 
-function Search(paginateConfig: PaginateConfig<any>) {
+export function Search(paginateConfig: PaginateConfig<any>) {
     if (!paginateConfig.searchableColumns) return
 
     return ApiQuery({
         name: 'search',
         description: `Search term to filter result values
-        ${p('Example', 'John')}
-        ${p(DEFAULT_VALUE_KEY, 'No default value')}
-        `,
+${p('Example', 'John')}
+${p(DEFAULT_VALUE_KEY, 'No default value')}
+`,
         required: false,
         type: 'string',
     })
 }
 
-function SearchBy(paginateConfig: PaginateConfig<any>) {
+export function SearchBy(paginateConfig: PaginateConfig<any>) {
     if (!paginateConfig.searchableColumns) return
 
     return ApiQuery({
         name: 'searchBy',
         description: `List of fields to search by term to filter result values
-        ${p(
-            'Example',
-            paginateConfig.searchableColumns.slice(0, Math.min(5, paginateConfig.searchableColumns.length)).join(',')
-        )}
-        ${p(DEFAULT_VALUE_KEY, 'By default all fields mentioned below will be used to search by term')}
-        ${li('Available Fields', paginateConfig.searchableColumns)}
-        `,
+${p(
+    'Example',
+    paginateConfig.searchableColumns.slice(0, Math.min(5, paginateConfig.searchableColumns.length)).join(',')
+)}
+${p(DEFAULT_VALUE_KEY, 'By default all fields mentioned below will be used to search by term')}
+${li('Available Fields', paginateConfig.searchableColumns)}
+`,
         required: false,
         isArray: true,
         type: 'string',
diff --git a/src/swagger/pagination-docs.spec.ts b/src/swagger/pagination-docs.spec.ts
@@ -72,7 +72,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'Page number to retrieve.If you provide invalid value the default page number will applied\n        <p>\n             <b>Example: </b> 1\n          </p>\n        <p>\n             <b>Default Value: </b> 1\n          </p>\n        ',
+                    'Page number to retrieve. If you provide invalid value the default page number will applied\n\n**Example:** 1\n\n\n**Default Value:** 1\n\n',
                 schema: {
                     type: 'number',
                 },
@@ -82,7 +82,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'Number of records per page.\n      <p>\n             <b>Example: </b> 20\n          </p>\n      <p>\n             <b>Default Value: </b> 20\n          </p>\n      <p>\n             <b>Max Value: </b> 100\n          </p>\n\n      If provided value is greater than max value, max value will be applied.\n      ',
+                    'Number of records per page.\n\n\n**Example:** 20\n\n\n\n**Default Value:** 20\n\n\n\n**Max Value:** 100\n\n\nIf provided value is greater than max value, max value will be applied.\n',
                 schema: {
                     type: 'number',
                 },
@@ -92,7 +92,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'Parameter to sort by.\n      <p>To sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting</p>\n      <p>\n             <b>Format: </b> fieldName:DIRECTION\n          </p>\n      <p>\n             <b>Example: </b> sortBy=id:DESC&sortBy=createdAt:ASC\n          </p>\n      <p>\n             <b>Default Value: </b> No default sorting specified, the result order is not guaranteed\n          </p>\n      <h4>Available Fields</h4><ul><li>id</li></ul>\n      ',
+                    'Parameter to sort by.\nTo sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting\n\n**Format:** {fieldName}:{DIRECTION}\n\n\n**Example:** sortBy=id:DESC\n\n\n**Default Value:** No default sorting specified, the result order is not guaranteed if not provided\n\n**Available Fields**\n- id\n',
                 schema: {
                     type: 'array',
                     items: {
@@ -154,7 +154,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'Page number to retrieve.If you provide invalid value the default page number will applied\n        <p>\n             <b>Example: </b> 1\n          </p>\n        <p>\n             <b>Default Value: </b> 1\n          </p>\n        ',
+                    'Page number to retrieve. If you provide invalid value the default page number will applied\n\n**Example:** 1\n\n\n**Default Value:** 1\n\n',
                 schema: {
                     type: 'number',
                 },
@@ -164,7 +164,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'Number of records per page.\n      <p>\n             <b>Example: </b> 20\n          </p>\n      <p>\n             <b>Default Value: </b> 20\n          </p>\n      <p>\n             <b>Max Value: </b> 100\n          </p>\n\n      If provided value is greater than max value, max value will be applied.\n      ',
+                    'Number of records per page.\n\n\n**Example:** 20\n\n\n\n**Default Value:** 20\n\n\n\n**Max Value:** 100\n\n\nIf provided value is greater than max value, max value will be applied.\n',
                 schema: {
                     type: 'number',
                 },
@@ -174,7 +174,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'Filter by id query param.\n          <p>\n             <b>Format: </b> filter.id={$not}:OPERATION:VALUE\n          </p>\n          <p>\n             <b>Example: </b> filter.id=$not:$like:John Doe&filter.id=like:John\n          </p>\n          <h4>Available Operations</h4><ul><li>$and</li>\n<li>$or</li>\n<li>$not</li>\n<li>$eq</li>\n<li>$gt</li>\n<li>$gte</li>\n<li>$in</li>\n<li>$null</li>\n<li>$lt</li>\n<li>$lte</li>\n<li>$btw</li>\n<li>$ilike</li>\n<li>$sw</li>\n<li>$contains</li></ul>',
+                    'Filter by id query param.\n\n**Format:** filter.id={$not}:OPERATION:VALUE\n\n\n\n**Example:** filter.id=$btw:John Doe&filter.id=$contains:John Doe\n\n**Available Operations**\n- $eq\n\n- $gt\n\n- $gte\n\n- $in\n\n- $null\n\n- $lt\n\n- $lte\n\n- $btw\n\n- $ilike\n\n- $sw\n\n- $contains\n\n- $not\n\n- $and\n\n- $or',
                 schema: {
                     type: 'array',
                     items: {
@@ -187,7 +187,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'Filter by name query param.\n          <p>\n             <b>Format: </b> filter.name={$not}:OPERATION:VALUE\n          </p>\n          <p>\n             <b>Example: </b> filter.name=$not:$like:John Doe&filter.name=like:John\n          </p>\n          <h4>Available Operations</h4><ul><li>$eq</li>\n<li>$not</li></ul>',
+                    'Filter by name query param.\n\n**Format:** filter.name={$not}:OPERATION:VALUE\n\n\n\n**Example:** filter.name=$eq:John Doe\n\n**Available Operations**\n- $eq\n\n- $not\n\n- $and\n\n- $or',
                 schema: {
                     type: 'array',
                     items: {
@@ -200,7 +200,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'Parameter to sort by.\n      <p>To sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting</p>\n      <p>\n             <b>Format: </b> fieldName:DIRECTION\n          </p>\n      <p>\n             <b>Example: </b> sortBy=id:DESC&sortBy=createdAt:ASC\n          </p>\n      <p>\n             <b>Default Value: </b> id:DESC\n          </p>\n      <h4>Available Fields</h4><ul><li>id</li></ul>\n      ',
+                    'Parameter to sort by.\nTo sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting\n\n**Format:** {fieldName}:{DIRECTION}\n\n\n**Example:** sortBy=id:DESC\n\n\n**Default Value:** id:DESC\n\n**Available Fields**\n- id\n',
                 schema: {
                     type: 'array',
                     items: {
@@ -214,7 +214,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'Search term to filter result values\n        <p>\n             <b>Example: </b> John\n          </p>\n        <p>\n             <b>Default Value: </b> No default value\n          </p>\n        ',
+                    'Search term to filter result values\n\n**Example:** John\n\n\n**Default Value:** No default value\n\n',
                 schema: {
                     type: 'string',
                 },
@@ -224,7 +224,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'List of fields to search by term to filter result values\n        <p>\n             <b>Example: </b> name\n          </p>\n        <p>\n             <b>Default Value: </b> By default all fields mentioned below will be used to search by term\n          </p>\n        <h4>Available Fields</h4><ul><li>name</li></ul>\n        ',
+                    'List of fields to search by term to filter result values\n\n**Example:** name\n\n\n**Default Value:** By default all fields mentioned below will be used to search by term\n\n**Available Fields**\n- name\n',
                 schema: {
                     type: 'array',
                     items: {
@@ -237,7 +237,7 @@ describe('PaginatedEndpoint decorator', () => {
                 required: false,
                 in: 'query',
                 description:
-                    'List of fields to select.\n      <p>\n             <b>Example: </b> id,name\n          </p>\n      <p>\n             <b>Default Value: </b> By default all fields returns. If you want to select only some fields, provide them in query param\n          </p>\n      ',
+                    'List of fields to select.\n\n**Example:** id,name\n\n\n**Default Value:** By default all fields returns. If you want to select only some fields, provide them in query param\n\n',
                 schema: {
                     type: 'string',
                 },
