[Api-ref] Add worker cleanup for service docs api

Allow triggering cleanup from API was introduced in cinder[1], but it's
not documented in the API docs. This change is to add it in the API docs.
[1] https://review.openstack.org/#/c/363010/

Closes-bug: #1708809
Change-Id: Iadec39e8411a598372bc19bb566627a143faa0d8

api-ref/source/v3/index.rst

@@ -47,3 +47,4 @@ Block Storage API V3 (CURRENT)
 .. quota-sets should arguably live closer to limits, but that would mess up
    our nice alphabetical ordering
 .. include:: quota-sets.inc
+.. include:: worker-cleanup.inc

api-ref/source/v3/parameters.yaml

@@ -516,6 +516,12 @@ backups_number_usage:
   in: body
   required: true
   type: object
+binary:
+  description: |
+    The service binary.
+  in: body
+  required: false
+  type: string
 bootable:
   description: |
     Enables or disables the bootable attribute. You
@@ -797,6 +803,12 @@ detached_at:
   in: body
   required: false
   type: string
+disabled:
+  description: |
+    Filter by disabled status.
+  in: body
+  required: false
+  type: boolean
 disk_format:
   description: |
     Disk format for the new image. Default is raw.
@@ -1140,6 +1152,12 @@ is_public_1:
   in: body
   required: false
   type: boolean
+is_up:
+  description: |
+    Filter by up/down status.
+  in: body
+  required: false
+  type: boolean
 key:
   description: |
     The metadata key name for the metadata that you
@@ -1874,6 +1892,12 @@ resource_filters:
   in: body
   required: true
   type: array
+resource_id:
+  description: |
+    The UUID of a resource to cleanup.
+  in: body
+  required: false
+  type: string
 resource_type:
   description: |
     The resource type corresponding to ``resource_uuid``.
@@ -1905,6 +1929,12 @@ safe_to_manage:
   in: body
   required: true
   type: boolean
+service_id:
+  description: |
+    UUID for the cleanup service.
+  in: body
+  required: false
+  type: string
 service_state:
   description: |
     The state of the service. One of ``available`` or ``unavailable``.

api-ref/source/v3/samples/worker-cleanup-request.json

@@ -0,0 +1,9 @@
+{
+    "cluster": "test",
+    "disabled": "True",
+    "host": "127.0.0.1",
+    "is_up": "True",
+    "binary": "cinder-volume",
+    "resource_id": "b122f668-d15a-40f8-af21-38d218796ab8",
+    "resource_type": "Volume"
+}

api-ref/source/v3/samples/worker-cleanup-response.json

@@ -0,0 +1,11 @@
+{
+    "cleaning": [
+        {
+            "id": "dd233343-er34-fr43-54ss-vfdfft433fdf",
+            "host": "127.0.0.1",
+            "binary": "cinder-volume",
+            "cluster_name": "test"
+        }
+    ],
+    "unavailable": []
+}

api-ref/source/v3/worker-cleanup.inc

@@ -0,0 +1,57 @@
+.. -*- rst -*-
+
+Workers (workers)
+=================
+
+
+Cleanup services
+~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST v3/{project_id}/workers/cleanup
+
+Request cleanup of services with optional filtering. This API is only
+available with microversion 3.24 or later.
+
+
+
+Normal response codes: 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - cluster: cluster_mutex
+   - host: host_service
+   - binary: binary
+   - is-up: is_up
+   - disabled: disabled
+   - resource-id: resource_id
+   - resource-type: resource_type
+
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/worker-cleanup-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - host: host_service
+   - binary: binary
+   - id: service_id
+   - cluster_name: cluster_mutex
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/worker-cleanup-response.json
+   :language: javascript