From ad739f8e137ad50bfba7a66712704fab29c4f2f3 Mon Sep 17 00:00:00 2001
From: Matt Riedemann <mriedem@us.ibm.com>
Date: Wed, 11 May 2016 11:12:55 -0400
Subject: [PATCH] api-ref: parameter validation for os-security-group-rules

Cleans up a bunch of the types and descriptions for the
parameters.

Removes some extraneous unused parameters.

Added descriptions for the request and response to point out
that group_id and cidr are optional but one or the other is
required and depending on what comes in the request influences
what comes back in the response.

Part of blueprint api-ref-in-rst

Change-Id: I1084fa7ec46373cc989d1d93bb667ac59a62e38a
---
 api-ref/source/os-security-group-rules.inc | 17 +++---
 api-ref/source/parameters.yaml             | 60 ++++++++++------------
 2 files changed, 39 insertions(+), 38 deletions(-)

diff --git a/api-ref/source/os-security-group-rules.inc b/api-ref/source/os-security-group-rules.inc
index 00468c11360e..896fb68cfbf3 100644
--- a/api-ref/source/os-security-group-rules.inc
+++ b/api-ref/source/os-security-group-rules.inc
@@ -1,5 +1,4 @@
 .. -*- rst -*-
-.. needs:parameter_verification
 .. needs:example_verification
 .. needs:body_verification
 
@@ -14,7 +13,8 @@ Create Security Group Rule
 
 .. rest_method:: POST /v2.1/{tenant_id}/os-security-group-rules
 
-Creates a rule for a security group.
+Creates a rule for a security group. Either ``cidr`` or ``group_id`` must be
+specified when creating a rule.
 
 Normal response codes: 200
 
@@ -31,7 +31,7 @@ Request
   - ip_protocol: ip_protocol
   - from_port: from_port
   - to_port: to_port
-  - cidr: cidr
+  - cidr: secgroup_rule_cidr
   - group_id: group_id
 
 .. TODO(sdague): we currently have no samples here
@@ -43,18 +43,23 @@ Request
 Response
 --------
 
+The ``group`` is empty if ``group_id`` was not provided on the request.
+
+The ``ip_range`` is empty if ``cidr`` was not provided on the request.
+
 .. rest_parameters:: parameters.yaml
 
   - security_group_rule: security_group_rule
   - ip_protocol: ip_protocol
   - from_port: from_port
   - to_port: to_port
-  - ip_range: ip_range
-  - cidr: cidr
-  - id: id
+  - ip_range: secgroup_rule_ip_range
+  - cidr: secgroup_rule_cidr
+  - id: secgroup_rule_id
   - group: group
   - parent_group_id: parent_group_id
   - name: name
+  - tenant_id: secgroup_tenant_id_body
 
 .. TODO(sdague): we currently have no samples here
    **Example Create security group rule: JSON response**
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 1804e25cc05b..6e2c9fab3ec1 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1110,18 +1110,13 @@ from_port:
   in: body
   required: true
   type: integer
-from_port_1:
-  description: |
-    Port at start of range.
-  in: body
-  required: true
-  type: integer
 group:
   description: |
-    A ``group`` object. Includes the tenant ID and the source security group name.
+    A ``group`` object. Includes the ``tenant_id`` and the source security
+    group ``name``.
   in: body
   required: true
-  type: string
+  type: object
 group_id:
   description: |
     The source security group ID.
@@ -1329,30 +1324,13 @@ ip_protocol:
   in: body
   required: true
   type: string
-ip_protocol_1:
-  description: |
-    The IP protocol: ICMP, TCP, or UDP.
-  in: body
-  required: true
-  type: string
 ip_range:
   description: |
     The range of IP addresses to use for creating floating IPs.
   in: body
   required: true
   type: string
-ip_range_1:
-  description: |
-    An IP range object.
-  in: body
-  required: true
-  type: string
-ip_range_2:
-  description: |
-    An ``ip_range`` object.
-  in: body
-  required: true
-  type: string
+# TODO(mriedem): this needs to be renamed and used in os-floating-ips-bulk.inc
 ip_range_3:
   description: |
     The range of IP addresses from which to bulk-delete floating IPs.
@@ -1926,6 +1904,30 @@ rules_1:
   in: body
   required: true
   type: string
+secgroup_rule_cidr:
+  description: |
+    The CIDR for address range.
+  in: body
+  required: false
+  type: string
+secgroup_rule_id:
+  description: |
+    The security group rule ID.
+  in: body
+  required: true
+  type: string
+secgroup_rule_ip_range:
+  description: |
+    An IP range object. Includes the security group rule ``cidr``.
+  in: body
+  required: true
+  type: object
+secgroup_tenant_id_body:
+  description: |
+    The UUID of the tenant that owns this security group.
+  in: body
+  required: true
+  type: string
 security_group:
   description: |
     Specify the ``security_group`` action in the request body.
@@ -2130,12 +2132,6 @@ to_port:
   in: body
   required: true
   type: integer
-to_port_1:
-  description: |
-    Port at end of range.
-  in: body
-  required: true
-  type: integer
 type:
   description: |
     The snapshot type. A valid value is ``qcow2``.