[DRAFT] docs: API documentation improvements

astro/src/components/api/APIField.astro

@@ -22,20 +22,23 @@ const { name, description, type, required, optional, immutable, since, defaults,
 ---
 {/*If you put the API field inside a conditional block it can break the markdown parsing, `renderif` solves that problem  */}
 {/* Note: if you use a description parameter instead of a body, you'll get a single-line version */}
-{ renderif && <div class='border-t border-slate-300 dark:border-slate-800'>
-  <div class="flex flex-wrap mt-6 space-x-3 items-baseline">
-    <code class="api-field-name">{ name }</code>
-    { type && <span class="dark:text-gray-400 text-gray-500 text-sm pt-1">{type}</span> }
-    { description && <span class="px-3">{description}</span> }
-    { required && <span class="px-[6px] py-1 rounded-md text-orange-500 border-orange-500 border-2 dark:font-semibold font-bold uppercase text-xs dark:text-[10px]">required</span> }
-    { defaults && <span class="pt-1 dark:text-gray-400 text-gray-500 text-sm justify-center">Defaults to {defaults}</span> }
-    { show_since && since && <AvailableSince since={since} /> }
-    { immutable && <span class="px-3 text-orange-500 text-sm font-semibold uppercase">Immutable</span> }
-    { deprecated && <span class="text-red-700 text-sm">DEPRECATED</span> }
-    { readonly && <ReadOnly /> }
-  </div>
-  <div class="ml-4 mb-7 font-normal text-sm">
-    <slot></slot>
-  </div>
+{ renderif && <div class='border-t border-slate-300 dark:border-slate-800 pb-6'>
+  <details class="group">
+    <summary class="flex flex-wrap mt-6 space-x-3 items-baseline cursor-pointer list-none [&::-webkit-details-marker]:hidden">
+      <span class="text-slate-400 dark:text-slate-500 text-xs mr-1 group-open:rotate-90 transition-transform inline-block">▶</span>
+      <code class="api-field-name">{ name }</code>
+      { type && <span class="dark:text-gray-400 text-gray-500 text-sm pt-1">{type}</span> }
+      { description && <span class="px-3">{description}</span> }
+      { required && <span class="px-[6px] py-1 rounded-md text-orange-500 border-orange-500 border-2 dark:font-semibold font-bold uppercase text-xs dark:text-[10px]">required</span> }
+      { defaults && <span class="pt-1 dark:text-gray-400 text-gray-500 text-sm justify-center">Defaults to {defaults}</span> }
+      { show_since && since && <AvailableSince since={since} /> }
+      { immutable && <span class="px-3 text-orange-500 text-sm font-semibold uppercase">Immutable</span> }
+      { deprecated && <span class="text-red-700 text-sm">DEPRECATED</span> }
+      { readonly && <ReadOnly /> }
+    </summary>
+    <div class="ml-4 mt-3 font-normal text-sm">
+      <slot></slot>
+    </div>
+  </details>
 </div>
 }

astro/src/content/docs/apis/_user-request-body.mdx

@@ -25,7 +25,7 @@ You must specify either the **email** or the **username** or both for the User.
   <APIField name="disableDomainBlock" type="Boolean" optional defaults="false" since="1.30.0">
     A tenant has the option to configure one or more email domains to be blocked in order to restrict email domains during user create or update.
 
-    Setting this property equal to `true` will override the tenant configuration. See <InlineField>tenant.registrationConfiguration.blockedDomains</InlineField> in the [Tenant API](tenants).
+    Setting this property equal to `true` will override the tenant configuration. See <InlineField>tenant.registrationConfiguration.blockedDomains</InlineField> in the [Tenant API](/docs/apis/tenants).
   </APIField>
 
   { props.http_method === 'POST' &&

astro/src/content/docs/apis/users/bulk-delete.mdx

@@ -0,0 +1,103 @@
+---
+title: Bulk Delete Users
+description: API documentation for the FusionAuth Bulk Delete Users API.
+order: 6
+---
+import APIBlock from 'src/components/api/APIBlock.astro';
+import APIField from 'src/components/api/APIField.astro';
+import API from 'src/components/api/API.astro';
+import Aside from 'src/components/Aside.astro';
+import InlineField from 'src/components/InlineField.astro';
+import JSON from 'src/components/JSON.astro';
+import SearchPreprocessingWarning from "src/content/docs/_shared/_search-preprocessing-warning.mdx";
+import StandardDeleteResponseCodes from 'src/content/docs/apis/_standard-delete-response-codes.astro';
+import UserBulkDeleteRequestBody from 'src/content/docs/apis/_user-bulk-delete-request-body.mdx';
+import UserBulkDeleteResponseBody from 'src/content/docs/apis/_user-bulk-delete-response-body.mdx';
+import XFusionauthTenantIdHeaderScopedOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-scoped-operation.mdx';
+
+This API is used to deactivate or delete multiple users in a single request.
+
+<Aside type="note">
+This API has some limitations when FusionAuth is configured to use the database as the user search engine.  These limitations are noted on the impacted request parameters below.
+</Aside>
+
+## Request
+
+<API method="DELETE" uri="/api/user/bulk?userId={userId}&userId={userId}" authentication={["api-key"]} title="Deactivate Users by User Id"/>
+
+<API method="DELETE" uri="/api/user/bulk?queryString={queryString}&dryRun=false&limit=10000" authentication={["api-key"]} title="Deactivate Users by Search Query String"/>
+
+<API method="DELETE" uri="/api/user/bulk?query={query}&dryRun=false&limit=10000" authentication={["api-key"]} title="Deactivate Users by Raw JSON Search Query"/>
+
+<API method="DELETE" uri="/api/user/bulk?userId={userId}&userId={userId}&hardDelete=true" authentication={["api-key"]} title="Permanently Delete Users by User Id"/>
+
+<API method="DELETE" uri="/api/user/bulk?queryString={queryString}&hardDelete=true&dryRun=false&limit=10000" authentication={["api-key"]} title="Permanently Delete Users by Search Query String"/>
+
+<API method="DELETE" uri="/api/user/bulk?query={query}&hardDelete=true&dryRun=false&limit=10000" authentication={["api-key"]} title="Permanently Delete Users by Raw JSON Search Query"/>
+
+### Request Parameters
+
+<APIBlock>
+  <APIField name="dryRun" type="Boolean" optional defaults="false">
+    To preview the user Ids to be deleted by the request without applying the requested action set this value to `true`.
+  </APIField>
+  <APIField name="hardDelete" type="Boolean" optional defaults="false">
+    To Permanently delete a user from FusionAuth set this value to `true`. Once a user has been permanently deleted, the action cannot be undone. When this value is set to `false` the user is marked as inactive and the user will be unable log into FusionAuth. This action may be undone by reactivating the user.
+  </APIField>
+  <APIField name="limit" type="Integer" optional defaults="10,000" since="1.48.0">
+    The maximum number of users to delete in one call.
+
+    You may use this parameter to process deletes in batches in order to limit individual request processing time and the number of user Ids on the response.
+  </APIField>
+  <APIField name="query" type="String" optional since="1.13.0">
+    The raw JSON Elasticsearch query that is used to search for Users. The <InlineField>userId</InlineField>, <InlineField>query</InlineField>, and <InlineField>queryString</InlineField>  parameters are mutually exclusive, they are listed here in order of precedence.
+
+    It is necessary to use the <InlineField>query</InlineField> parameter when querying against `registrations` in order to achieve expected results, as this field is defined as a [nested datatype](https://www.elastic.co/guide/en/elasticsearch/reference/6.3/nested.html) in the Elasticsearch mapping.
+
+    <Aside type="note" title="Database search engine">
+      This parameter is not compatible with the database search engine, it may only be used when Elasticsearch is configured as the user search engine.
+    </Aside>
+  </APIField>
+</APIBlock>
+
+<APIField name="queryString" type="String" optional since="1.13.0">
+  The Elasticsearch query string that is used to search for Users to be deleted. The <InlineField>userId</InlineField>, <InlineField>query</InlineField>, and <InlineField>queryString</InlineField>  parameters are mutually exclusive, they are listed here in order of precedence.
+
+  <SearchPreprocessingWarning/>
+
+  <Aside type="note" title="Database search engine">
+    The Elasticsearch query string DSL is not supported for the database search engine.  Database search limits effective queries to single search terms that may match the following fields on the User:
+    * `firstName`
+    * `lastName`
+    * `fullName`
+    * `email`
+    * `username`
+
+    The following is an example bulk delete request with a `queryString` value that is compatible with the database search engine:
+
+    `DELETE /api/user/bulk?queryString=jared%40fusionauth.io`
+  </Aside>
+</APIField>
+
+
+<APIField name="userId" type="UUID" optional>
+  The Id of the User to delete. Repeat this parameter for each user to be deleted. The <InlineField>userId</InlineField>, <InlineField>query</InlineField>, and <InlineField>queryString</InlineField>  parameters are mutually exclusive, they are listed here in order of precedence.
+</APIField>
+
+<XFusionauthTenantIdHeaderScopedOperation />
+
+### Using request body
+
+<API method="DELETE" uri="/api/user/bulk" authentication={["api-key"]} title="Bulk delete using the request body. This allows for larger requests than are possible using request parameters."/>
+
+<XFusionauthTenantIdHeaderScopedOperation />
+
+<UserBulkDeleteRequestBody />
+
+## Response
+
+The response for this API contains the information for the Users that were affected by the request.
+
+<StandardDeleteResponseCodes success_code="200" success_message="The request was successful. The response will contain a JSON body." webhook_event />
+
+<UserBulkDeleteResponseBody />