openstack/neutron-lib
Code Issues Proposed changes

api-ref: Fix api-ref for subnets

Browse Source 
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
This commit is contained in:
Anindita Das 2016-08-20 22:35:20 +00:00
parent a420cf8f5e
commit 10907011b7
7 changed files with 488 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

256
api-ref/source/v2/parameters.yaml
View File

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

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

@ -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"
}
}

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

@ -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"
}
}

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

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

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

@ -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"
}
]
}

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

@ -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"
}
]
}

235
api-ref/source/v2/subnets.inc
View File

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