Cleanup Services V3 documentation

The commit removes '...' and '--some-attribute--' references and
replaces them with more realistic examples. Also change all
'http://identity' to 'https://identity'.

Change-Id: I769bc2d18e45e2c0ba922fc6b95e48b252a15ad0

openstack-identity-api/v3/src/markdown/identity-api-v3.md

@@ -879,15 +879,19 @@ Additional required attributes:
 
 Optional attributes:
 
-- `name` (string)
+- `description` (string)
 
-  User-facing name of the service.
+  User-facing description of the service.
 
 - `enabled` (boolean)
 
   Setting this value to `false` prevents the service and its endpoints from
   appearing in the service catalog.
 
+- `name` (string)
+
+  User-facing name of the service.
+
 Example entity:
 
     {
@@ -1922,24 +1926,26 @@ Response:
     {
         "services": [
             {
-                "id": "--service-id--",
+                "description": "OpenStack Volume Service",
+                "id": "ee057c",
                 "links": {
-                    "self": "http://identity:35357/v3/services/--service-id--"
+                    "self": "https://identity:35357/v3/services/ee057c"
                 },
-                "name": "--service-name",
+                "name": "Cinder",
                 "type": "volume"
             },
             {
-                "id": "--service-id--",
+                "description": "OpenStack Identity Service",
+                "id": "5e70df",
                 "links": {
-                    "self": "http://identity:35357/v3/services/--service-id--"
+                    "self": "https://identity:35357/v3/services/5e70df"
                 },
-                "name": "--service-name",
+                "name": "Keystone",
                 "type": "identity"
             }
         ],
         "links": {
-            "self": "http://identity:35357/v3/services",
+            "self": "https://identity:35357/v3/services",
             "previous": null,
             "next": null
         }
@@ -1953,11 +1959,12 @@ Response:
 
     {
         "service": {
-            "id": "--service-id--",
+            "description": "OpenStack Volume Service",
+            "id": "ee057c",
             "links": {
-                "self": "http://identity:35357/v3/services/--service-id--"
+                "self": "https://identity:35357/v3/services/ee057c"
             },
-            "name": "--service-name",
+            "name": "Cinder",
             "type": "volume"
         }
     }
@@ -1968,8 +1975,9 @@ Request:
 
     {
         "service": {
-            "name": "--optional--",
-            "type": "..."
+            "description": "OpenStack Compute Service",
+            "name": "Nova",
+            "type": "compute"
         }
     }
 
@@ -1979,12 +1987,13 @@ Response:
 
     {
         "service": {
-            "id": "--service-id--",
+            "description": "OpenStack Compute Service",
+            "id": "520ec2",
             "links": {
-                "self": "http://identity:35357/v3/services/--service-id--"
+                "self": "https://identity:35357/v3/services/520ec2"
             },
-            "name": "--service-name--",
-            "type": "volume"
+            "name": "Nova",
+            "type": "compute"
         }
     }
 
@@ -1999,12 +2008,13 @@ Response:
 
     {
         "service": {
-            "id": "--service-id--",
+            "description": "OpenStack Image Service",
+            "id": "520ec2",
             "links": {
-                "self": "http://identity:35357/v3/services/--service-id--"
+                "self": "https://identity:35357/v3/services/520ec2"
             },
-            "name": "--service-name",
-            "type": "volume"
+            "name": "Glance",
+            "type": "image"
         }
     }