Module 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, ResolvableApi, DefaultSchema, models::Version};

use std::fs::File;

let mut fd = File::open("my_spec.yaml").unwrap(); // yaml or json
let api: ResolvableApi<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 serde_derive; // NOTE: We're using serde for decoding stuff.

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

use std::fs::File;

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

#[paperclip::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: ResolvableApi<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:

• walk through the nodes, find $ref fields and assign references to the actual definitions.
• identify anonymous definitions in body parameters and response schemas and add them to the known map of definitions.

#[cfg(feature = "codegen")] {

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

#[cfg(feature = "codegen")] {
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::codegen::Emitter;

pub use self::codegen::EmitterState;

pub use paperclip_core::v2::serde_json;

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.

Traits

Schema

Interface for the Schema object.

Functions

from_reader

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

from_reader_v3

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

Type Aliases

ResolvableApi

OpenAPI v2 spec which can be traversed and resolved for codegen.