From 2c0832d9ec3a7071d2e5a4f651b38706a678343d Mon Sep 17 00:00:00 2001 From: Artem Goncharov Date: Thu, 26 Sep 2024 18:53:01 +0200 Subject: [PATCH] chore: Further doc clarifications --- openstack_sdk/src/api.rs | 31 +++++++++++++++++++++++--- openstack_sdk/src/api/block_storage.rs | 2 +- openstack_sdk/src/api/compute.rs | 1 + openstack_sdk/src/api/identity.rs | 1 + openstack_sdk/src/api/image.rs | 1 + openstack_sdk/src/api/load_balancer.rs | 2 +- openstack_sdk/src/api/network.rs | 1 + openstack_sdk/src/api/object_store.rs | 1 + 8 files changed, 35 insertions(+), 5 deletions(-) diff --git a/openstack_sdk/src/api.rs b/openstack_sdk/src/api.rs index f5d15b063..5e3f13918 100644 --- a/openstack_sdk/src/api.rs +++ b/openstack_sdk/src/api.rs @@ -54,7 +54,12 @@ //! //! ## Find combinator //! -//! Finding resource by `name` or `id` is possible using [`find`](fn@find) combinator. +//! Finding resource by `name` or `id` is possible using [`find`](fn@find) combinator. First a API +//! request to get resource directly by the identified (i.e. `flavors/`) is done. When it +//! returns positive data it is used as a find response. Otherwise list API call is invoked +//! (passing name filter parameter when available). Single operation return entry is used as find +//! result otherwise an error is returned. Only endpoints implementing +//! [`Findable`] trait support that. //! //! ``` //! use openstack_sdk::api::QueryAsync; @@ -71,9 +76,29 @@ //! # } //! ``` //! +//! When identifier is clearly known to be `name` [`find`](fn@find_by_name) is more useful and is +//! saving unnecessary API roundtrip for attempting to query resource by the identificator and +//! immediately triggers listing operation. +//! +//! ``` +//! use openstack_sdk::api::QueryAsync; +//! use openstack_sdk::api::find_by_name; +//! # use openstack_sdk::{AsyncOpenStack, config::ConfigFile, OpenStackError}; +//! # use http::Response; +//! # async fn func() -> Result<(), OpenStackError> { +//! # let cfg = ConfigFile::new().unwrap(); +//! # let profile = cfg.get_cloud_config("devstack".to_string()).unwrap().unwrap(); +//! # let client = AsyncOpenStack::new(&profile).await?; +//! # let ep = openstack_sdk::api::compute::v2::flavor::find::Request::builder().build().unwrap(); +//! let data_raw: serde_json::Value = find_by_name(ep).query_async(&client).await?; +//! # Ok(()) +//! # } +//! ``` +//! //! ## Pagination combinator //! -//! Support for querying paginated resources is covered using [`paged`](fn@paged) combinator. +//! Support for querying paginated resources is covered using [`paged`](fn@paged) combinator. The +//! endpoint must implement [`Pageable`] trait to support this combinator. //! //! ``` //! use openstack_sdk::api::{QueryAsync, Pagination}; @@ -170,7 +195,7 @@ pub use self::paged::Paged; pub use self::paged::Pagination; pub use self::paged::PaginationError; -pub use self::find::{find, find_by_name}; +pub use self::find::{find, find_by_name, Findable}; pub use self::params::JsonBodyParams; pub use self::params::ParamValue; diff --git a/openstack_sdk/src/api/block_storage.rs b/openstack_sdk/src/api/block_storage.rs index 065d62e70..5bda0b25b 100644 --- a/openstack_sdk/src/api/block_storage.rs +++ b/openstack_sdk/src/api/block_storage.rs @@ -12,5 +12,5 @@ // // SPDX-License-Identifier: Apache-2.0 -//! Block Storage API bindings +//! Block Storage (Cinder) API bindings pub mod v3; diff --git a/openstack_sdk/src/api/compute.rs b/openstack_sdk/src/api/compute.rs index b43b4deea..57fd7b879 100644 --- a/openstack_sdk/src/api/compute.rs +++ b/openstack_sdk/src/api/compute.rs @@ -12,4 +12,5 @@ // // SPDX-License-Identifier: Apache-2.0 +//! Compute service (Nova) bindings pub mod v2; diff --git a/openstack_sdk/src/api/identity.rs b/openstack_sdk/src/api/identity.rs index d093ad99e..713de4e4b 100644 --- a/openstack_sdk/src/api/identity.rs +++ b/openstack_sdk/src/api/identity.rs @@ -12,4 +12,5 @@ // // SPDX-License-Identifier: Apache-2.0 +//! Identity API (Keystone) bindings pub mod v3; diff --git a/openstack_sdk/src/api/image.rs b/openstack_sdk/src/api/image.rs index b43b4deea..504099738 100644 --- a/openstack_sdk/src/api/image.rs +++ b/openstack_sdk/src/api/image.rs @@ -12,4 +12,5 @@ // // SPDX-License-Identifier: Apache-2.0 +//! Image API (Glance) bindings pub mod v2; diff --git a/openstack_sdk/src/api/load_balancer.rs b/openstack_sdk/src/api/load_balancer.rs index e8206759c..a03696e6b 100644 --- a/openstack_sdk/src/api/load_balancer.rs +++ b/openstack_sdk/src/api/load_balancer.rs @@ -12,5 +12,5 @@ // // SPDX-License-Identifier: Apache-2.0 -//! Load Balancing API bindings +//! Load Balancing API (Octavia) bindings pub mod v2; diff --git a/openstack_sdk/src/api/network.rs b/openstack_sdk/src/api/network.rs index b43b4deea..f5008f3d8 100644 --- a/openstack_sdk/src/api/network.rs +++ b/openstack_sdk/src/api/network.rs @@ -12,4 +12,5 @@ // // SPDX-License-Identifier: Apache-2.0 +//! Network API (Neutron) bindings pub mod v2; diff --git a/openstack_sdk/src/api/object_store.rs b/openstack_sdk/src/api/object_store.rs index 082d14090..acdb7342e 100644 --- a/openstack_sdk/src/api/object_store.rs +++ b/openstack_sdk/src/api/object_store.rs @@ -12,4 +12,5 @@ // // SPDX-License-Identifier: Apache-2.0 +//! Object-Store API (Swift) bindings pub mod v1;