api-ref: Fix api-ref for subnets

Added request/response parameters for the rest_method::
   GET /v2.0/subnets
   POST /v2.0/subnets (Create Subnet)
   POST /v2.0/subnets (Bulk Create Subnet)
   GET /v2.0/subnets/{subnet_id} (Show Subnet Details)
   PUT /v2.0/subnets/{subnet_id} (Update Subnet)
   DELETE /v2.0/subnets/{subnet_id} (Delete Subnet)

Co-Authored-By: Akihiro Motoki <amotoki@gmail.com>
Change-Id: I7cfba70c6805161ee9e26135fe08f5075e94d755
Partially-Implements: blueprint neutron-in-tree-api-ref
Partial-Bug: #1613151

api-ref/source/v2/parameters.yaml

@@ -169,11 +169,11 @@ service_id:
   in: path
   required: false
   type: string
-subnet_id_2:
+subnet_id-path:
   description: |
-    The UUID of the subnet.
+    The ID of the subnet.
   in: path
-  required: false
+  required: true
   type: string
 subnetpool_id:
   description: |
@@ -1835,12 +1835,6 @@ ip_version_1:
   in: body
   required: true
   type: integer
-ip_version_2:
-  description: |
-    The IP protocol version. Value is ``4`` or ``6``.
-  in: body
-  required: true
-  type: integer
 ip_version_3:
   description: |
     The IP version (4 or 6) of the subnet.
@@ -3821,6 +3815,209 @@ sub_ports:
   in: body
   required: true
   type: array
+subnet-allocation_pools:
+  description: |
+    Allocation pools with ``start`` and ``end`` IP addresses
+    for this subnet.
+  in: body
+  required: true
+  type: array
+subnet-allocation_pools-request:
+  description: |
+    Allocation pools with ``start`` and ``end`` IP addresses
+    for this subnet. If allocation_pools are not specified, OpenStack
+    Networking automatically allocates pools for covering all IP addresses
+    in the CIDR, excluding the address reserved for the subnet gateway by
+    default.
+  in: body
+  required: false
+  type: array
+subnet-created_at:
+  description: |
+    Time at which the subnet has been created.
+  in: body
+  required: true
+  type: string
+subnet-description:
+  description: |
+    Description of the subnet.
+  in: body
+  required: true
+  type: string
+subnet-dns_nameservers:
+  description: |
+    List of dns name servers associated with the subnet.
+  in: body
+  required: true
+  type: array
+subnet-dns_nameservers-request:
+  description: |
+    List of dns name servers associated with the subnet. Default is an
+    empty list.
+  in: body
+  required: false
+  type: array
+subnet-enable_dhcp:
+  description: |
+    Indicates whether dhcp is enabled or disabled
+    for the subnet.
+  in: body
+  required: true
+  type: boolean
+subnet-enable_dhcp-request:
+  description: |
+    Indicates whether dhcp is enabled or disabled
+    for the subnet. Default is ``true``.
+  in: body
+  required: false
+  type: boolean
+subnet-gateway_ip:
+  description: |
+    Gateway IP of this subnet. If the value is ``null`` that implies no
+    gateway is associated with the subnet.
+  in: body
+  required: true
+  type: string
+subnet-gateway_ip-request:
+  description: |
+    Gateway IP of this subnet. If the value is ``null`` that implies no
+    gateway is associated with the subnet. If the gateway_ip is not
+    specified, OpenStack Networking allocates an address from the CIDR
+    for the gateway for the subnet by default.
+  in: body
+  required: false
+  type: string
+subnet-host_routes:
+  description: |
+    Additional routes for the subnet. A list of dictionaries with
+    ``destination`` and ``nexthop`` parameters.
+  in: body
+  required: true
+  type: array
+subnet-host_routes-request:
+  description: |
+    Additional routes for the subnet. A list of dictionaries with
+    ``destination`` and ``nexthop`` parameters. Default value is
+    an empty list.
+  in: body
+  required: false
+  type: array
+subnet-id-body:
+  description: |
+    The ID of the subnet.
+  in: body
+  required: true
+  type: string
+subnet-ip_version:
+  description: |
+    The IP protocol version. Value is ``4`` or ``6``.
+  in: body
+  required: true
+  type: integer
+subnet-ipv6_address_mode:
+  description: |
+    The IPv6 address modes specifies mechanisms for assigning IP addresses.
+    Value is ``slaac``, ``dhcpv6-stateful``, ``dhcpv6-stateless`` or ``null``.
+  in: body
+  required: true
+  type: string
+subnet-ipv6_address_mode-request:
+  description: |
+    The IPv6 address modes specifies mechanisms for assigning IP addresses.
+    Value is ``slaac``, ``dhcpv6-stateful``, ``dhcpv6-stateless``.
+  in: body
+  required: false
+  type: string
+subnet-ipv6_ra_mode:
+  description: |
+    The IPv6 router advertisement specifies whether the networking service
+    should transmit ICMPv6 packets, for a subnet. Value is ``slaac``,
+    ``dhcpv6-stateful``, ``dhcpv6-stateless`` or ``null``.
+  in: body
+  required: true
+  type: string
+subnet-ipv6_ra_mode-request:
+  description: |
+    The IPv6 router advertisement specifies whether the networking service
+    should transmit ICMPv6 packets, for a subnet. Value is ``slaac``,
+    ``dhcpv6-stateful``, ``dhcpv6-stateless``.
+  in: body
+  required: false
+  type: string
+subnet-name:
+  description: |
+    Human-readable name of the resource.
+  in: body
+  required: true
+  type: string
+subnet-name-request:
+  description: |
+    Human-readable name of the resource. Default is an empty string.
+  in: body
+  required: false
+  type: string
+subnet-name-update-request:
+  description: |
+    Human-readable name of the resource.
+  in: body
+  required: false
+  type: string
+subnet-network_id:
+  description: |
+    The ID of the network to which the subnet belongs.
+  in: body
+  required: true
+  type: string
+subnet-obj:
+  description: |
+    A ``subnet`` object.
+  in: body
+  required: true
+  type: string
+subnet-revision_number:
+  description: |
+    The revision number of the subnet.
+  in: body
+  required: true
+  type: string
+subnet-segment_id:
+  description: |
+    The ID of a network segment the subnet is associated with.
+    It is available when ``segment`` extension is enabled.
+  in: body
+  required: true
+  type: string
+subnet-segment_id-request:
+  description: |
+    The ID of a network segment the subnet is associated with.
+    It is available when ``segment`` extension is enabled.
+  in: body
+  required: false
+  type: string
+subnet-service_types:
+  description: |
+    The service types associated with the subnet.
+  in: body
+  required: true
+  type: string
+subnet-subnetpool_id:
+  description: |
+    The ID of the subnet pool associated with the subnet.
+  in: body
+  required: true
+  type: string
+subnet-subnetpool_id-request:
+  description: |
+    The ID of the subnet pool associated with the subnet.
+  in: body
+  required: false
+  type: string
+subnet-updated_at:
+  description: |
+    Time at which the subnet has been updated.
+  in: body
+  required: true
+  type: string
 subnet_id:
   description: |
     If you specify only a subnet UUID, OpenStack
@@ -3830,41 +4027,6 @@ subnet_id:
   in: body
   required: false
   type: string
-subnet_id_1:
-  description: |
-    The UUID of the subnet to which the port is
-    attached.
-  in: body
-  required: true
-  type: string
-subnet_id_3:
-  description: |
-    (Deprecated) The subnet where the VPN service should
-    be provided.
-  in: body
-  required: false
-  type: string
-subnet_id_4:
-  description: |
-    (Deprecated) The subnet where the VPN service should
-    be provided.
-  in: body
-  required: true
-  type: string
-subnet_id_6:
-  description: |
-    If you omit this parameter, LBaaS uses the
-    ``vip_subnet_id`` parameter value for the subnet UUID.
-  in: body
-  required: false
-  type: integer
-subnet_id_7:
-  description: |
-    The UUID of the subnet on which to allocate the
-    virtual IP (VIP) address.
-  in: body
-  required: true
-  type: string
 subnet_ip_availability:
   description: |
     This is dictionary showing subnet IP
@@ -3897,6 +4059,12 @@ subnets:
   in: body
   required: true
   type: array
+subnets-obj:
+  description: |
+    A list of ``subnet`` objects.
+  in: body
+  required: true
+  type: array
 subnets_1:
   description: |
     The associated subnets.

api-ref/source/v2/samples/subnets/subnet-create-request.json

@@ -2,6 +2,6 @@
     "subnet": {
         "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
         "ip_version": 4,
-        "cidr": "10.0.0.1"
+        "cidr": "192.168.199.0/24"
     }
 }

api-ref/source/v2/samples/subnets/subnet-create-response.json

@@ -17,6 +17,14 @@
         "ip_version": 4,
         "gateway_ip": "192.168.199.1",
         "cidr": "192.168.199.0/24",
-        "id": "3b80198d-4f7b-4f77-9ef5-774d54e17126"
+        "id": "3b80198d-4f7b-4f77-9ef5-774d54e17126",
+        "created_at": "2016-10-10T14:35:47Z",
+        "description": "",
+        "ipv6_address_mode": null,
+        "ipv6_ra_mode": null,
+        "revision_number": 2,
+        "service_types": [],
+        "subnetpool_id": null,
+        "updated_at": "2016-10-10T14:35:47Z"
     }
 }

api-ref/source/v2/samples/subnets/subnet-show-response.json

@@ -19,6 +19,12 @@
         "gateway_ip": "192.0.0.1",
         "cidr": "192.0.0.0/8",
         "updated_at": "2016-03-08T20:19:41",
-        "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
+        "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b",
+        "description": "",
+        "ipv6_address_mode": null,
+        "ipv6_ra_mode": null,
+        "revision_number": 2,
+        "service_types": [],
+        "subnetpool_id": null
     }
 }

api-ref/source/v2/samples/subnets/subnets-create-bulk-response.json

@@ -18,7 +18,15 @@
             "network_id": "e6031bc2-901a-4c66-82da-f4c32ed89406",
             "segment_id": null,
             "project_id": "d19231fc08ec4bc4829b668040d34512",
-            "tenant_id": "d19231fc08ec4bc4829b668040d34512"
+            "tenant_id": "d19231fc08ec4bc4829b668040d34512",
+            "created_at": "2016-10-10T14:35:47Z",
+            "description": "",
+            "ipv6_address_mode": null,
+            "ipv6_ra_mode": null,
+            "revision_number": 2,
+            "service_types": [],
+            "subnetpool_id": null,
+            "updated_at": "2016-10-10T14:35:47Z"
         },
         {
             "allocation_pools": [
@@ -38,7 +46,15 @@
             "network_id": "64239a54-dcc4-4b39-920b-b37c2144effa",
             "segment_id": null,
             "project_id": "d19231fc08ec4bc4829b668040d34512",
-            "tenant_id": "d19231fc08ec4bc4829b668040d34512"
+            "tenant_id": "d19231fc08ec4bc4829b668040d34512",
+            "created_at": "2016-10-10T14:35:34Z",
+            "description": "",
+            "ipv6_address_mode": null,
+            "ipv6_ra_mode": null,
+            "revision_number": 2,
+            "service_types": [],
+            "subnetpool_id": null,
+            "updated_at": "2016-10-10T14:35:34Z"
         }
     ]
 }

api-ref/source/v2/samples/subnets/subnets-list-response.json

@@ -18,7 +18,15 @@
             "ip_version": 4,
             "gateway_ip": "10.0.0.1",
             "cidr": "10.0.0.0/24",
-            "id": "08eae331-0402-425a-923c-34f7cfe39c1b"
+            "id": "08eae331-0402-425a-923c-34f7cfe39c1b",
+            "created_at": "2016-10-10T14:35:34Z",
+            "description": "",
+            "ipv6_address_mode": null,
+            "ipv6_ra_mode": null,
+            "revision_number": 2,
+            "service_types": [],
+            "subnetpool_id": null,
+            "updated_at": "2016-10-10T14:35:34Z"
         },
         {
             "name": "my_subnet",
@@ -38,7 +46,15 @@
             "ip_version": 4,
             "gateway_ip": "192.0.0.1",
             "cidr": "192.0.0.0/8",
-            "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b"
+            "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b",
+            "created_at": "2016-10-10T14:35:47Z",
+            "description": "",
+            "ipv6_address_mode": null,
+            "ipv6_ra_mode": null,
+            "revision_number": 2,
+            "service_types": [],
+            "subnetpool_id": null,
+            "updated_at": "2016-10-10T14:35:47Z"
         }
     ]
 }

api-ref/source/v2/subnets.inc

@@ -1,8 +1,4 @@
 .. -*- rst -*-
-.. needs:method_verification
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 =======
 Subnets
@@ -24,6 +20,12 @@ user has administrative role. You can control which attributes
 are returned by using the fields query parameter. You can filter
 results by using query string parameters.
 
+Use the ``fields`` query parameter to control which fields are
+returned in the response body. Additionally, you can filter results
+by using query string parameters. For information, see `Filtering
+and Column Selection <https://wiki.openstack.org/wiki/Neutron/APIv2
+-specification#Filtering_and_Column_Selection>`__.
+
 Normal response codes: 200
 
 Error response codes: 401
@@ -31,6 +33,38 @@ Error response codes: 401
 Request
 -------
 
+.. rest_parameters:: parameters.yaml
+
+   - fields: fields
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - subnets: subnets-obj
+   - id: subnet-id-body
+   - tenant_id: project_id
+   - project_id: project_id
+   - name: subnet-name
+   - enable_dhcp: subnet-enable_dhcp
+   - network_id: subnet-network_id
+   - dns_nameservers: subnet-dns_nameservers
+   - allocation_pools: subnet-allocation_pools
+   - host_routes: subnet-host_routes
+   - ip_version: subnet-ip_version
+   - gateway_ip: subnet-gateway_ip
+   - cidr: cidr
+   - created_at: subnet-created_at
+   - description: subnet-description
+   - ipv6_address_mode: subnet-ipv6_address_mode
+   - ipv6_ra_mode: subnet-ipv6_ra_mode
+   - revision_number: subnet-revision_number
+   - segment_id: subnet-segment_id
+   - service_types: subnet-service_types
+   - subnetpool_id: subnet-subnetpool_id
+   - updated_at: subnet-updated_at
+
 Response Example
 ----------------
 
@@ -80,12 +114,32 @@ subnets must be associated with segments or none of them can be.
 Neutron enforces this invariant. Currently, routed networks are
 only supported for provider networks.
 
-Error response codes: 201,404,403,401,400,409
+Normal response codes: 201
+
+Error response codes: 404, 403, 401, 400, 409
 
 Request
 -------
 
-.. .. rest_parameters:: parameters.yaml
+.. rest_parameters:: parameters.yaml
+
+   - subnet: subnet-obj
+   - tenant_id: project_id-request
+   - project_id: project_id-request
+   - name: subnet-name-request
+   - enable_dhcp: subnet-enable_dhcp-request
+   - network_id: subnet-network_id
+   - dns_nameservers: subnet-dns_nameservers-request
+   - allocation_pools: subnet-allocation_pools-request
+   - host_routes: subnet-host_routes-request
+   - ip_version: subnet-ip_version
+   - gateway_ip: subnet-gateway_ip-request
+   - cidr: cidr
+   - description: description-request
+   - ipv6_address_mode: subnet-ipv6_address_mode-request
+   - ipv6_ra_mode: subnet-ipv6_ra_mode-request
+   - segment_id: subnet-segment_id-request
+   - subnetpool_id: subnet-subnetpool_id-request
 
 Request Example
 ---------------
@@ -93,6 +147,40 @@ Request Example
 .. literalinclude:: samples/subnets/subnet-create-request.json
    :language: javascript
 
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - subnet: subnet-obj
+   - id: subnet-id-body
+   - tenant_id: project_id
+   - project_id: project_id
+   - name: subnet-name
+   - enable_dhcp: subnet-enable_dhcp
+   - network_id: subnet-network_id
+   - dns_nameservers: subnet-dns_nameservers
+   - allocation_pools: subnet-allocation_pools
+   - host_routes: subnet-host_routes
+   - ip_version: subnet-ip_version
+   - gateway_ip: subnet-gateway_ip
+   - cidr: cidr
+   - created_at: subnet-created_at
+   - description: subnet-description
+   - ipv6_address_mode: subnet-ipv6_address_mode
+   - ipv6_ra_mode: subnet-ipv6_ra_mode
+   - revision_number: subnet-revision_number
+   - service_types: subnet-service_types
+   - subnetpool_id: subnet-subnetpool_id
+   - segment_id: subnet-segment_id
+   - updated_at: subnet-updated_at
+
+Response Example
+----------------
+
+.. literalinclude:: samples/subnets/subnet-create-response.json
+   :language: javascript
+
 Bulk create subnet
 ==================
 
@@ -103,12 +191,32 @@ Creates multiple subnets in a single request. Specify a list of subnets in the r
 The bulk create operation is always atomic. Either all or no
 subnets in the request body are created.
 
-Error response codes: 201,404,403,401,400,409
+Normal response codes: 201
+
+Error response codes: 404, 403, 401, 400, 409
 
 Request
 -------
 
-.. .. rest_parameters:: parameters.yaml
+.. rest_parameters:: parameters.yaml
+
+   - subnets: subnets-obj
+   - tenant_id: project_id-request
+   - project_id: project_id-request
+   - name: subnet-name-request
+   - enable_dhcp: subnet-enable_dhcp-request
+   - network_id: subnet-network_id
+   - dns_nameservers: subnet-dns_nameservers-request
+   - allocation_pools: subnet-allocation_pools-request
+   - host_routes: subnet-host_routes-request
+   - ip_version: subnet-ip_version
+   - gateway_ip: subnet-gateway_ip-request
+   - cidr: cidr
+   - description: description-request
+   - ipv6_address_mode: subnet-ipv6_address_mode-request
+   - ipv6_ra_mode: subnet-ipv6_ra_mode-request
+   - segment_id: subnet-segment_id-request
+   - subnetpool_id: subnet-subnetpool_id-request
 
 Request Example
 ---------------
@@ -116,6 +224,40 @@ Request Example
 .. literalinclude:: samples/subnets/subnets-create-bulk-request.json
    :language: javascript
 
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - subnets: subnets-obj
+   - id: subnet-id-body
+   - tenant_id: project_id
+   - project_id: project_id
+   - name: subnet-name
+   - enable_dhcp: subnet-enable_dhcp
+   - network_id: subnet-network_id
+   - dns_nameservers: subnet-dns_nameservers
+   - allocation_pools: subnet-allocation_pools
+   - host_routes: subnet-host_routes
+   - ip_version: subnet-ip_version
+   - gateway_ip: subnet-gateway_ip
+   - cidr: cidr
+   - created_at: subnet-created_at
+   - description: subnet-description
+   - ipv6_address_mode: subnet-ipv6_address_mode
+   - ipv6_ra_mode: subnet-ipv6_ra_mode
+   - revision_number: subnet-revision_number
+   - segment_id: subnet-segment_id
+   - service_types: subnet-service_types
+   - subnetpool_id: subnet-subnetpool_id
+   - updated_at: subnet-updated_at
+
+Response Example
+----------------
+
+.. literalinclude:: samples/subnets/subnets-create-bulk-response.json
+   :language: javascript
+
 Show subnet details
 ===================
 
@@ -134,7 +276,35 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - subnet_id: subnet_id
+   - subnet_id: subnet_id-path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - subnet: subnet-obj
+   - id: subnet-id-body
+   - tenant_id: project_id
+   - project_id: project_id
+   - created_at: subnet-created_at
+   - name: subnet-name
+   - enable_dhcp: subnet-enable_dhcp
+   - network_id: subnet-network_id
+   - dns_nameservers: subnet-dns_nameservers
+   - allocation_pools: subnet-allocation_pools
+   - host_routes: subnet-host_routes
+   - ip_version: subnet-ip_version
+   - gateway_ip: subnet-gateway_ip
+   - cidr: cidr
+   - updated_at: subnet-updated_at
+   - description: subnet-description
+   - ipv6_address_mode: subnet-ipv6_address_mode
+   - ipv6_ra_mode: subnet-ipv6_ra_mode
+   - revision_number: subnet-revision_number
+   - segment_id: subnet-segment_id
+   - service_types: subnet-service_types
+   - subnetpool_id: subnet-subnetpool_id
 
 Response Example
 ----------------
@@ -162,7 +332,13 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - subnet_id: subnet_id
+   - subnet_id: subnet_id-path
+   - name: subnet-name-update-request
+   - enable_dhcp: subnet-enable_dhcp-request
+   - dns_nameservers: subnet-dns_nameservers-request
+   - allocation_pools: subnet-allocation_pools-request
+   - host_routes: subnet-host_routes-request
+   - gateway_ip: subnet-gateway_ip-request
 
 Request Example
 ---------------
@@ -170,6 +346,34 @@ Request Example
 .. literalinclude:: samples/subnets/subnet-update-request.json
    :language: javascript
 
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - subnet: subnet-obj
+   - id: subnet-id-body
+   - tenant_id: project_id
+   - project_id: project_id
+   - name: subnet-name
+   - enable_dhcp: subnet-enable_dhcp
+   - network_id: subnet-network_id
+   - dns_nameservers: subnet-dns_nameservers
+   - allocation_pools: subnet-allocation_pools
+   - host_routes: subnet-host_routes
+   - ip_version: subnet-ip_version
+   - gateway_ip: subnet-gateway_ip
+   - cidr: cidr
+   - created_at: subnet-created_at
+   - description: subnet-description
+   - ipv6_address_mode: subnet-ipv6_address_mode
+   - ipv6_ra_mode: subnet-ipv6_ra_mode
+   - revision_number: subnet-revision_number
+   - segment_id: subnet-segment_id
+   - service_types: subnet-service_types
+   - subnetpool_id: subnet-subnetpool_id
+   - updated_at: subnet-updated_at
+
 Response Example
 ----------------
 
@@ -185,12 +389,19 @@ Deletes a subnet.
 
 The operation fails if subnet IP addresses are still allocated.
 
-Error response codes: 409,404,204,401
+Normal response codes: 204
+
+Error response codes: 404, 401
 
 Request
 -------
 
 .. rest_parameters:: parameters.yaml
 
-   - subnet_id: subnet_id
+   - subnet_id: subnet_id-path
+
+Response
+--------
+
+There is no body content for the response of a successful DELETE request.