Macro generate_api 

generate_api!() { /* proc-macro */ }

Generates a client from the given OpenAPI document

generate_api! can be invoked in two ways. The simple form, takes a path to the OpenAPI document:

generate_api!("path/to/spec.json");

The more complex form accepts the following key-value pairs in any order:

generate_api!(
    // spec can be a simple path string:
    spec = "path/to/spec.json",
    // Or a struct with path and relative_to:
    spec = { path = "path/to/spec.json", relative_to = OutDir },
    [ interface = ( Positional | Builder ), ]
    [ tags = ( Merged | Separate ), ]
    [ pre_hook = closure::or::path::to::function, ]
    [ post_hook = closure::or::path::to::function, ]
    [ pre_hook_async = closure::or::path::to::function, ]
    [ post_hook_async = closure::or::path::to::function, ]

    [ derives = [ path::to::DeriveMacro ], ]

    [ unknown_crates = (Generate | Allow | Deny ), ]
    [ crates = { "<crate-name>" = ("<version>" | "*" | "!" ) } ]

    [ patch = { TypeName = { [rename = NewTypeName], [derives = []] }, } ]
    [ replace = { TypeName = full_path::to::other::TypeName, }]
    [ convert = { { <schema> } = full_path::to::TypeName, }]
    [ timeout = u64 ]
);

The spec key is required; it is the OpenAPI document (JSON or YAML) from which the client is derived. It can be specified as a simple string path, or as a struct with path and relative_to fields. The relative_to field controls where the path is resolved from:

• ManifestDir: relative to CARGO_MANIFEST_DIR. This is the default when the spec is provided as a string path.
• OutDir: relative to OUT_DIR (useful for build script outputs).

The optional interface lets you specify either a Positional argument or Builder argument style; Positional is the default.

The optional tags may be Merged in which case all operations are methods on the Client struct or Separate in which case each tag is represented by an “extension trait” that Client implements. The default is Merged.

The optional inner_type is for ancillary data, stored with the generated client that can be used by the pre- and post-hooks.

The optional pre_hook is either a closure (that must be within parentheses: (fn |[inner,] request| { .. })) or a path to a function. The closure or function must take one or two parameters: the inner type (if one is specified) and a &reqwest::Request. This allows clients to examine requests before they’re sent to the server, for example to log them. The optional pre_hook_async is the async variant of the same.

The optional post_hook is either a closure (that must be within parentheses: (fn |[inner,] result| { .. })) or a path to a function. The closure or function must take one or two parameters: the inner type (if one is specified) and a &Result<reqwest::Response, reqwest::Error>. This allows clients to examine responses, for example to log them. The optional post_hook_async is the async variant of the same.

Additional options control type generation:

• derives: optional array of derive macro paths; the derive macros to be applied to all generated types

• struct_builder: optional boolean; (if true) generates a ::builder() method for each generated struct that can be used to specify each property and construct the struct

• unknown_crates: optional policy regarding the handling of schemas that contain the x-rust-type extension whose crates are not explicitly named in the crates section. The options are generate to ignore the extension and generate a de novo type, allow to use the named type (which may require the addition of a new dependency to compile, and which ignores version compatibility checks), or deny to produce a compile-time error (requiring the user to specify the crate’s disposition in the crates section).

• crates: optional map from crate name to the version of the crate in use. Types encountered with the Rust type extension (x-rust-type) will use types from the specified crates rather than generating them (within the constraints of type compatibility).

• patch: optional map from type to an object with the optional members rename and derives. This may be used to rename generated types or to apply additional (non-default) derive macros to them.

• replace: optional map from definition name to a replacement type. This may be used to skip generation of the named type and use a existing Rust type.

• convert: optional map from a JSON schema type defined in $defs to a replacement type. This may be used to skip generation of the schema and use an existing Rust type.

• timeout: the default connection timeout for the underlying reqwest client (15s if not specified)