peltzi / rust-netbox

rust-netbox provides an API client for DigitalOcean's NetBox IPAM and DCIM service.

Rust API client for Netbox

Netbox API client library for Rust. The client is auto-generated from the swagger.json provided by the modern Netbox APIs (min v2.3.2).

Overview

This API client was generated by the OpenAPI Generator project.

• Netbox API version: 3.0
• OpenAPI Generator CLI version v5.2.1
  • Build package: org.openapitools.codegen.languages.RustClientCodegen

Installation

Clone the project and add the following to Cargo.toml under [dependencies]:

    rust-netbox = { path = "<path to rust-netbox>" }

TODO: Publish to crates.io

Example

Example usage:

use rust_netbox::apis::client::APIClient;
use rust_netbox::apis::configuration::{Configuration, ApiKey};

fn main() {
    // Setup configuration
    let mut config = Configuration::new();
    config.base_path = "https://<your Netbox address>/api"
        .to_string();

    config.api_key = Some(ApiKey {
        prefix: Some("Token ".to_string()), // https://netbox.readthedocs.io/en/stable/api/authentication/
        key: "<your Netbox API token>".to_string()
    });

    // Setup new API client with the configuration
    let api = APIClient::new(config);

    // Get IP address
    let ip = match api.ipam_api().ipam_ip_addresses_read(66) {
        Ok(ip) => ip,
        Err(error) => {
            panic!("Error getting IP: {:?}", error);
        }
    };
    println!("Got IP: {:?}", ip);
}

How to generate

This project uses cargo-make, netbox-docker and OpenAPI Generator CLI docker release to automate the generation of the client against desired version of Netbox. In order to build this project you need to have some required tooling present.

By modifying Netbox image version in the Makefile.toml you can easily generate your own version of the library that matches your exact version of Netbox if you desire.

Generation requirements

• Docker (tested with 19.03.8-ce)
• Docker compose (tested with 1.25.5)
• Rust (tested with version 1.43.0 installed with rustup)
  • cargo
  • rustc
• cargo-make (tested with 0.30.6)
• jq
• curl

TODO: Move generation tool chain to Docker container also (and run sub-tasks Docker in Docker style)

Generation process

The whole build process is run with [cargo-make][https://github.com/sagiegurari/cargo-make ]. See Makefile.toml. Build process leans heavily on the ability to run Docker containers.

To generate the client code run cargo make generate-client.

This step runs a live Netbox setup with docker-compose to fetch the up-to-date swagger.json and then runs openapi-generator-cli with Docker to generate the actual client code. After a successful generation you'll find the fetched swagger.json in build/swagger.json and client code in build/client/.

To move the generated client code into the repository from the build directory you have a cargo-make task for that too: cargo make full-sync.

To do both at (client generation and code moving) you can simply run cargo make full-upgrade.

Syncing and upgrading demand you have a non-dirty Git status present to avoid confusion with changes coming from the build.

Documentation

To get access to the crate's generated documentation, use:

cargo doc --open