progenitor/docs/positional-generation.md

Positional Generation

When the "positional" style is specified, Progenitor generates methods according to operations within an OpenAPI document. Each takes the following general form:

impl Client {
    pub async fn operation_name<'a>(
        &'a self,
        // Path parameters (if any) come first and are always mandatory
        path_parameter_1: String,
        path_parameter_2: u32,
        // Query parameters (if any) come next and may be optional
        query_parameter_1: String,
        query_parameter_2: Option<u32>,
        // A body parameter (if specified) comes last
        body: &types::ThisOperationBody,
    ) -> Result<
        ResponseValue<types::SuccessResponseType>,
        Error<types::ErrorResponseType>,
    > {
        // ...
    }

For more info on the ResponseValue<T> and Error<E> types, see progenitor_client.

Note that methods are async so must be awaited to get the response value.

Dropshot Paginated Operations

Dropshot defines a mechanism for pagination. If that mechanism is used for a particular operation, Progenitor will generate an additional method that produces a Stream. Consumers can iterate over all items in the paginated collection without manually fetching individual pages.

Here's the signature for a typical generated method:

    pub fn operation_name_stream<'a>(
        &'a self,
        // Specific parameters...
        limit: Option<std::num::NonZeroU32>,
    ) -> impl futures::Stream<
	    Item = Result<types::SuccessResponseType, Error<types::ErrorResponseType>>
    > + Unpin + '_ {
        // ...
    }

A typical consumer of this method might look like this:

    let mut stream = client.operation_name_stream(None);
    loop {
        match stream.try_next().await {
            Ok(Some(item)) => println!("item {:?}", item),
            Ok(None) => {
                println!("done.");
                break;
            }
            Err(_) => {
                println!("error!");
                break;
            }
        }
    }