From 603e484fb6128dface4945ebacbe8d0edb4f408e Mon Sep 17 00:00:00 2001
From: Fabio Oliveira <fabioaurelio1269@gmail.com>
Date: Mon, 10 Jan 2022 15:48:54 -0300
Subject: [PATCH] api-ref: Add share instances by share endpoint

The endpoint for /shares/{share_id}/instances was missing for the
share section.
This patch adds the section and update the existing one on
v2/shate_instances.

Closes-Bug: 1952673
Change-Id: Ie8412379c20528575d2e67485ce955bcf8c13eee
---
 .../share-instances-list-response.json        |  6 ++
 api-ref/source/share-instances.inc            | 13 +++-
 api-ref/source/shares.inc                     | 67 +++++++++++++++++++
 3 files changed, 83 insertions(+), 3 deletions(-)

diff --git a/api-ref/source/samples/share-instances-list-response.json b/api-ref/source/samples/share-instances-list-response.json
index 01a0fc34da..a30c94e2c3 100644
--- a/api-ref/source/samples/share-instances-list-response.json
+++ b/api-ref/source/samples/share-instances-list-response.json
@@ -11,6 +11,8 @@
             "cast_rules_to_readonly": false,
             "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
             "host": "manila2@generic1#GENERIC1",
+            "access_rules_status": "active",
+            "share_type_id": "78dee8a9-1ee6-4a29-9081-14e6596fbb96",
             "id": "081f7030-c54f-42f5-98ee-93a37393e0f2"
         },
         {
@@ -24,6 +26,8 @@
             "cast_rules_to_readonly": false,
             "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
             "host": "manila2@generic1#GENERIC1",
+            "access_rules_status": "active",
+            "share_type_id": "78dee8a9-1ee6-4a29-9081-14e6596fbb96",
             "id": "75559a8b-c90c-42a7-bda2-edbe86acfb7b"
         },
         {
@@ -37,6 +41,8 @@
             "cast_rules_to_readonly": false,
             "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
             "host": "manila2@generic1#GENERIC1",
+            "access_rules_status": "active",
+            "share_type_id": "78dee8a9-1ee6-4a29-9081-14e6596fbb96",
             "id": "48155648-2fd3-480d-b02b-44b995c24bab"
         }
     ]
diff --git a/api-ref/source/share-instances.inc b/api-ref/source/share-instances.inc
index 31781485be..b9103661a7 100644
--- a/api-ref/source/share-instances.inc
+++ b/api-ref/source/share-instances.inc
@@ -4,9 +4,14 @@
 Share instances (since API v2.3)
 ================================
 
-Administrators can list, show information for, explicitly set the
-state of, and force-delete share instances. Use the ``policy.json``
-file to grant permissions for these actions to other roles.
+A share instance is an internal representation for a share. A share that is
+replicated or is in the process of being migrated is physically stored in
+multiple locations. Each of these individual locations is called an "instance"
+within the Shared File Systems service. End users need not be concerned with
+this internal representation. As an administrator, you can list, show
+information for, explicitly set the state of, and force-delete share instances.
+Use the ``policy.json`` file to grant permissions for these actions to other
+roles.
 
 
 List share instances
@@ -58,6 +63,8 @@ Response parameters
    - share_network_id: share_network_id
    - share_server_id: share_server_id
    - host: host_resource_response
+   - access_rules_status: access_rules_status
+   - share_type_id: share_type_id
    - id: id_13
 
 Response example
diff --git a/api-ref/source/shares.inc b/api-ref/source/shares.inc
index e31aa86b72..cb22c661bd 100644
--- a/api-ref/source/shares.inc
+++ b/api-ref/source/shares.inc
@@ -328,6 +328,73 @@ Response example
    :language: javascript
 
 
+List share instances
+====================
+
+.. rest_method::  GET /v2/shares/{share_id}/instances
+
+.. versionadded:: 2.3
+
+Lists instances of a share.
+
+A share instance is an internal representation for a share. A share that is
+replicated or is in the process of being migrated is physically stored in
+multiple locations. Each of these individual locations is called an "instance"
+within the Shared File Systems service. End users need not be concerned with
+this internal representation. As an administrator, you can list all instances
+of a share through this endpoint resource. Use the ``policy.json`` file to
+grant permissions for this action to other roles.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - share_id: share_id
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: share_status_response
+   - access_rules_status: access_rules_status
+   - share_id: share_id_share_instances_response
+   - progress: progress_share_instance
+   - availability_zone: availability_zone
+   - created_at: created_at
+   - replica_state: replica_state
+   - export_location: export_location
+   - export_locations: export_locations
+   - cast_rules_to_readonly: share_instance_cast_rules_to_readonly
+   - share_network_id: share_network_id
+   - share_server_id: share_server_id
+   - host: host_resource_response
+   - access_rules_status: access_rules_status
+   - share_type_id: share_type_id
+   - id: id_13
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-instances-list-response.json
+   :language: javascript
+
 Create share
 ============