diff options
author | Zuul <zuul@review.opendev.org> | 2022-03-17 15:35:42 +0000 |
---|---|---|
committer | Gerrit Code Review <review@openstack.org> | 2022-03-17 15:35:42 +0000 |
commit | e5a1997df840080d53e3bc2a12ac9169c3f96990 (patch) | |
tree | c3c1bbe5ffa92e3c5a6b815ac8d362006e4aa759 /ironic | |
parent | 687694c83ccd61371cf89816ef7602ae9fed0dd0 (diff) | |
parent | 3e631a5931c9a3d53d78438339adfeeae5fa5a70 (diff) | |
download | ironic-e5a1997df840080d53e3bc2a12ac9169c3f96990.tar.gz |
Merge "Create API documentation from docstrings"
Diffstat (limited to 'ironic')
-rw-r--r-- | ironic/api/controllers/v1/allocation.py | 53 | ||||
-rw-r--r-- | ironic/api/controllers/v1/driver.py | 27 | ||||
-rw-r--r-- | ironic/api/controllers/v1/node.py | 6 |
3 files changed, 54 insertions, 32 deletions
diff --git a/ironic/api/controllers/v1/allocation.py b/ironic/api/controllers/v1/allocation.py index be7e41c64..7884df1fa 100644 --- a/ironic/api/controllers/v1/allocation.py +++ b/ironic/api/controllers/v1/allocation.py @@ -259,20 +259,17 @@ class AllocationsController(pecan.rest.RestController): owner=None): """Retrieve a list of allocations. - :param node: UUID or name of a node, to get only allocations for that - node. - :param resource_class: Filter by requested resource class. - :param state: Filter by allocation state. - :param marker: pagination marker for large data sets. - :param limit: maximum number of resources to return in a single result. - This value cannot be larger than the value of max_limit - in the [api] section of the ironic configuration, or only - max_limit resources will be returned. - :param sort_key: column to sort results by. Default: id. - :param sort_dir: direction to sort. "asc" or "desc". Default: asc. - :param fields: Optional, a list with a specified set of fields - of the resource to be returned. - :param owner: Filter by owner. + .. parameters:: ../../api-ref/source/parameters.yaml + + :node: r_allocation_node + :resource_class: req_allocation_resource_class + :state: r_allocation_state + :marker: marker + :limit: limit + :sort_key: sort_key + :sort_dir: sort_dir + :fields: fields + :owner: r_owner """ owner = api_utils.check_list_policy('allocation', owner) @@ -291,9 +288,10 @@ class AllocationsController(pecan.rest.RestController): def get_one(self, allocation_ident, fields=None): """Retrieve information about the given allocation. - :param allocation_ident: UUID or logical name of an allocation. - :param fields: Optional, a list with a specified set of fields - of the resource to be returned. + .. parameters:: ../../api-ref/source/parameters.yaml + + :allocation_ident: allocation_ident + :fields: fields """ rpc_allocation = api_utils.check_allocation_policy_and_retrieve( 'baremetal:allocation:get', allocation_ident) @@ -341,7 +339,9 @@ class AllocationsController(pecan.rest.RestController): def post(self, allocation): """Create a new allocation. - :param allocation: an allocation within the request body. + .. parameters:: ../../api-ref/source/parameters.yaml + + :allocation: req_allocation_name """ context = api.request.context cdict = context.to_policy_values() @@ -472,8 +472,10 @@ class AllocationsController(pecan.rest.RestController): def patch(self, allocation_ident, patch): """Update an existing allocation. - :param allocation_ident: UUID or logical name of an allocation. - :param patch: a json PATCH document to apply to this allocation. + .. parameters:: ../../api-ref/source/parameters.yaml + + :allocation_ident: allocation_ident + :patch: allocation_patch """ if not api_utils.allow_allocation_update(): raise webob_exc.HTTPMethodNotAllowed(_( @@ -513,7 +515,9 @@ class AllocationsController(pecan.rest.RestController): def delete(self, allocation_ident): """Delete an allocation. - :param allocation_ident: UUID or logical name of an allocation. + .. parameters:: ../../api-ref/source/parameters.yaml + + :allocation_ident: allocation_ident """ context = api.request.context rpc_allocation = api_utils.check_allocation_policy_and_retrieve( @@ -556,6 +560,12 @@ class NodeAllocationController(pecan.rest.RestController): @method.expose() @args.validate(fields=args.string_list) def get_all(self, fields=None): + """Get all allocations. + + .. parameters:: ../../api-ref/source/parameters.yaml + + :fields: fields + """ parent_node = self.parent_node_ident result = self.inner._get_allocations_collection( parent_node, @@ -572,6 +582,7 @@ class NodeAllocationController(pecan.rest.RestController): @METRICS.timer('NodeAllocationController.delete') @method.expose(status_code=http_client.NO_CONTENT) def delete(self): + """Delete an allocation.""" context = api.request.context rpc_node = api_utils.get_rpc_node_with_suffix(self.parent_node_ident) diff --git a/ironic/api/controllers/v1/driver.py b/ironic/api/controllers/v1/driver.py index 2775ed284..f117c327f 100644 --- a/ironic/api/controllers/v1/driver.py +++ b/ironic/api/controllers/v1/driver.py @@ -225,7 +225,7 @@ class DriverPassthruController(rest.RestController): :param driver_name: name of the driver. :returns: dictionary with <vendor method name>:<method metadata> entries. - :raises: DriverNotFound if the driver name is invalid or the + :raises DriverNotFound: if the driver name is invalid or the driver cannot be loaded. """ api_utils.check_policy('baremetal:driver:vendor_passthru') @@ -272,15 +272,20 @@ class DriverRaidController(rest.RestController): def logical_disk_properties(self, driver_name): """Returns the logical disk properties for the driver. - :param driver_name: Name of the driver. - :returns: A dictionary containing the properties that can be mentioned - for logical disks and a textual description for them. - :raises: UnsupportedDriverExtension if the driver doesn't - support RAID configuration. - :raises: NotAcceptable, if requested version of the API is less than - 1.12. - :raises: DriverNotFound, if driver is not loaded on any of the - conductors. + .. parameters:: ../../api-ref/source/parameters.yaml + + :driver_name: Name of the driver. + + .. return:: + + Success: + A dictionary containing the properties that can be mentioned + + Failure: + :UnsupportedDriverExtension: If the driver doesn't support RAID + configuration. + :NotAcceptable: If requested version of the API is less than 1.12. + :DriverNotFound: If driver is not loaded on any of the conductors. """ api_utils.check_policy( 'baremetal:driver:get_raid_logical_disk_properties') @@ -377,7 +382,7 @@ class DriversController(rest.RestController): :param driver_name: name of the driver. :returns: dictionary with <property name>:<property description> entries. - :raises: DriverNotFound (HTTP 404) if the driver name is invalid or + :raises DriverNotFound (HTTP 404): if the driver name is invalid or the driver cannot be loaded. """ api_utils.check_policy('baremetal:driver:get_properties') diff --git a/ironic/api/controllers/v1/node.py b/ironic/api/controllers/v1/node.py index bfba203d1..f182e2fd2 100644 --- a/ironic/api/controllers/v1/node.py +++ b/ironic/api/controllers/v1/node.py @@ -2442,6 +2442,12 @@ class NodesController(rest.RestController): """Create a new node. :param node: a node within the request body. + + **Example Node creation request:** + + .. literalinclude:: + ../../../../api-ref/source/samples/node-create-request-dynamic.json + :language: javascript """ if self.from_chassis: raise exception.OperationNotPermitted() |