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

@@ -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**

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``.