[][src]Module paperclip::v2

Utilities related to the OpenAPI v2 specification.

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;
#[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();

Now, if codegen feature is enabled (it is by default), we can use the emitter to emit the API into some path. But first, we need to resolve the raw schema. During resolution, we:

let resolved = api.resolve().unwrap();
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;

Modules

codegen

Code generation for OpenAPI v2.

im

Interior mutability stuff.

models

Models used by OpenAPI v2.

schema

Traits used for code and spec generation.

Structs

DefaultSchema

Default schema if your schema doesn't have any custom fields.

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.

Type Definitions

Api

OpenAPI v2 spec.