From 36f5c84148461e1a917bdd1c87b219c19ab559cb Mon Sep 17 00:00:00 2001
From: anguoming <agm_daydayup@foxmail.com>
Date: Sat, 23 Sep 2023 14:29:18 +0800
Subject: [PATCH] add api ref for enable/disable device

Change-Id: Ifb607e170321ca28a0447d117c05a755fee4c12c
---
 api-ref/source/devices.inc     | 46 +++++++++++++++++++++++++++++++++-
 api-ref/source/parameters.yaml |  6 +++++
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/api-ref/source/devices.inc b/api-ref/source/devices.inc
index ff0b8908..b1bc9ce3 100644
--- a/api-ref/source/devices.inc
+++ b/api-ref/source/devices.inc
@@ -4,7 +4,7 @@
 Devices
 +++++++
 
-Lists, shows details for devices.
+Lists, shows details for devices. Enable or disable for a device.
 
 A `device` represent a physical card like FPGA card or GPU card.
 
@@ -40,6 +40,7 @@ Response
   - std_board_info: device_std_board_info_resp
   - vendor_board_info: device_vendor_board_info_resp
   - hostname: hostname_resp
+  - status: device_status_resp
   - created_at: created
   - updated_at: updated
   - links: links
@@ -77,6 +78,7 @@ Response
   - std_board_info: device_std_board_info_resp
   - vendor_board_info: device_vendor_board_info_resp
   - hostname: hostname_resp
+  - status: device_status_resp
   - created_at: created
   - updated_at: updated
   - links: links
@@ -85,3 +87,45 @@ Response
 
 .. literalinclude:: ../../doc/api_samples/devices/devices-getone-resp.json
    :language: javascript
+
+Enable a device
+---------------
+
+.. rest_method:: POST /v2/devices/{device_uuid}/enable
+
+Set the device to enabled status.
+
+Normal response codes: 200
+
+Error response codes: 404(the device is not found),403(the role is not admin)
+
+Request
+=======
+.. rest_parameters:: parameters.yaml
+
+  - device_uuid: device_uuid
+
+Response
+========
+There is no body content for the response of a successful request.
+
+Disable a device
+----------------
+
+.. rest_method:: POST /v2/devices/{device_uuid}/disable
+
+Set the device to maintaining status.
+
+Normal response codes: 200
+
+Error response codes: 404(the device is not found),403(the role is not admin)
+
+Request
+=======
+.. rest_parameters:: parameters.yaml
+
+  - device_uuid: device_uuid
+
+Response
+========
+There is no body content for the response of a successful request.
\ No newline at end of file
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 4c0ad3ce..82afbbf7 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -305,6 +305,12 @@ device_rp_uuid_bind_unbind_req:
   in: body
   required: true
   type: string
+device_status_resp:
+  description: |
+    The status of device.  One of maintaining or enabled.
+  in: body
+  required: true
+  type: string
 device_std_board_info_resp:
   description: |
     The standard board information of the device.