From 631b18bd12c981165ab1a171b43d881328cae746 Mon Sep 17 00:00:00 2001
From: Michael Johnson <johnsomor@gmail.com>
Date: Thu, 25 Mar 2021 00:01:43 +0000
Subject: [PATCH] Fix API reference for service statuses

This patch updates the "list service statuses" section of the API
reference to document the response parameters.
It also adds the missing "show service status" section.

Change-Id: If451fc099d2a3dc8ce77c807d9553da7c4122190
---
 api-ref/source/dns-api-v2-service-status.inc  | 64 +++++++++++++++++++
 api-ref/source/parameters.yaml                | 55 +++++++++++++++-
 .../service_status/service_status_show.json   | 14 ++++
 3 files changed, 130 insertions(+), 3 deletions(-)
 create mode 100644 api-ref/source/samples/service_status/service_status_show.json

diff --git a/api-ref/source/dns-api-v2-service-status.inc b/api-ref/source/dns-api-v2-service-status.inc
index c13182bb9..533fa3e32 100644
--- a/api-ref/source/dns-api-v2-service-status.inc
+++ b/api-ref/source/dns-api-v2-service-status.inc
@@ -44,7 +44,17 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - x-openstack-request-id: x-openstack-request-id
+   - capabilities: capabilities
+   - created_at: created_at
+   - heartbeated_at: heartbeated_at
+   - hostname: hostname
    - id: id
+   - links: links
+   - service_name: service_name
+   - service_statuses: service_statuses
+   - stats: stats
+   - status: status
+   - updated_at: updated_at
 
 
 Response Example
@@ -52,3 +62,57 @@ Response Example
 
 .. literalinclude:: samples/service_status/service_status_list.json
    :language: javascript
+
+Show a Service Status
+=====================
+
+.. rest_method::  GET /v2/service_statuses/{service_id}
+
+Show the status of a service.
+
+
+.. rest_status_code:: success status.yaml
+
+    - 200
+
+.. rest_status_code:: error status.yaml
+
+    - 400
+    - 401
+    - 403
+    - 404
+    - 405
+    - 503
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - service_id: path_service_id
+   - x-auth-token: x-auth-token
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - capabilities: capabilities
+   - created_at: created_at
+   - heartbeated_at: heartbeated_at
+   - hostname: hostname
+   - id: id
+   - links: links
+   - service_name: service_name
+   - stats: stats
+   - status: status
+   - updated_at: updated_at
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/service_status/service_status_show.json
+   :language: javascript
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 39dce4dfc..27332001c 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -85,6 +85,13 @@ path_recordset_id:
   required: true
   type: uuid
 
+path_service_id:
+  description: |
+    ID for the service.
+  in: path
+  required: true
+  type: uuid
+
 path_zone_export_id:
   description: |
     ID for this zone export
@@ -392,9 +399,16 @@ blacklist_pattern:
   required: true
   type: string
 
+capabilities:
+  description: |
+    Capabilities for the service.
+  in: body
+  required: true
+  type: dict
+
 created_at:
   description: |
-    Date / Time when resource was created
+    Date / Time when resource was created.
   in: body
   required: true
   type: datestamp
@@ -441,6 +455,20 @@ fptrd_name:
   required: true
   type: string
 
+heartbeated_at:
+  description: |
+    The timestamp when the last heartbeat was received.
+  in: body
+  required: true
+  type: datestamp
+
+hostname:
+  description: |
+    The hostname of the host with the service instance.
+  in: body
+  required: true
+  type: string
+
 id:
   description: |
     ID for the resource
@@ -613,9 +641,30 @@ resource_id:
   required: true
   type: string
 
+service_name:
+  description: |
+    The name of the Designate service instance.
+  in: body
+  required: true
+  type: string
+
+service_statuses:
+  description: |
+    A list of ``service_statuses`` objects.
+  in: body
+  required: true
+  type: array
+
+stats:
+  description: |
+    Statistics for the service.
+  in: body
+  required: true
+  type: dict
+
 status:
   description: |
-    status of the resource
+    The status of the resource.
   in: body
   required: true
   type: enum
@@ -664,7 +713,7 @@ tsigkey_secret:
 
 updated_at:
   description: |
-    Date / Time when resource last updated
+    Date / Time when resource last updated.
   in: body
   required: false
   type: datestamp
diff --git a/api-ref/source/samples/service_status/service_status_show.json b/api-ref/source/samples/service_status/service_status_show.json
new file mode 100644
index 000000000..f0328d8bd
--- /dev/null
+++ b/api-ref/source/samples/service_status/service_status_show.json
@@ -0,0 +1,14 @@
+{
+  "id": "c0bcb136-5f5c-4427-9f89-99d457819917",
+  "hostname": "dns-2.example.com",
+  "service_name": "central",
+  "status": "UP",
+  "stats": {},
+  "capabilities": {},
+  "heartbeated_at": "2021-03-24T23:51:12.000000",
+  "created_at": "2021-03-22T20:59:24.000000",
+  "updated_at": "2021-03-24T23:51:12.000000",
+  "links": {
+    "self": "http://10.21.21.88/v2/service_statuses/c0bcb136-5f5c-4427-9f89-99d457819917"
+  }
+}