[][src]Module paperclip::v2

Types and traits related to the OpenAPI v2 spec.

Detailed example

To parse your v2 spec, you begin with transforming the schema into a Rust struct. If your schema doesn't have custom properties, then you can use the DefaultSchema.

use paperclip::v2::{self, Api, DefaultSchema, models::Version};

use std::fs::File;

let mut fd = File::open("my_spec.yaml").unwrap(); // yaml or json
let api: Api<DefaultSchema> = v2::from_reader(&mut fd).unwrap();
assert_eq!(api.swagger, Version::V2);

On the other hand, if your schema does have custom properties which you'd like to parse, then use the #[api_v2_schema] proc macro.

For example, let's take the Kubernetes API spec which uses some custom thingmabobs. Let's say we're only interested in the x-kubernetes-patch-strategy field for now.

#[macro_use] extern crate paperclip_macros;
#[macro_use] extern crate serde_derive; // NOTE: We're using serde for decoding stuff.

use paperclip::v2::{self, Api};

use std::fs::File;

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
enum PatchStrategy {
    Merge,
    RetainKeys,
    #[serde(rename = "merge,retainKeys")]
    MergeAndRetain,
    #[serde(other)]
    Other,
}

#[api_v2_schema]
#[derive(Debug, Deserialize)]
struct K8sSchema {
    #[serde(rename = "x-kubernetes-patch-strategy")]
    patch_strategy: Option<PatchStrategy>,
}

// K8sSchema now implements `Schema` trait.
let mut fd = File::open("k8s_spec.yaml").unwrap();
let api: Api<K8sSchema> = v2::from_reader(&mut fd).unwrap();

Next stop is to resolve this raw schema i.e., walk through the nodes, find $ref fields and assign references to the corresponding definitions.

let resolved = api.resolve().unwrap();

Now, if codegen feature is enabled (it is by default), we can use the emitter to emit the API into some path.

use paperclip::v2::{DefaultEmitter, EmitterState, Emitter};

let mut state = EmitterState::default();
state.working_dir = "/path/to/my/crate".into();
let emitter = DefaultEmitter::from(state);
emitter.generate(&api).unwrap(); // generate code!

Re-exports

pub use self::codegen::DefaultEmitter;
pub use self::models::Api;
pub use self::models::DefaultSchema;

Modules

codegen

Code generation for OpenAPI v2.

im

Interior mutability stuff.

models

Models used by OpenAPI v2.

Structs

EmitterState

Holds the state for your schema emitter.

Traits

Emitter

Emitter represents the interface for generating the relevant modules, API object definitions and the associated calls.

Schema

Interface for the Schema object.

Functions

from_reader

Deserialize the schema from the given reader. Currently, this only supports JSON and YAML formats.