Struct Document

Source

pub struct Document { /* private fields */ }

Expand description

Every operation the document describes, in document order, plus the server it describes them against.

Implementations§

Source §

impl Document

Source

pub fn load(document: &str, overlays: &[&str]) -> Result<Self, LoadError>

Parse the vendor’s document, lay the adopter’s Overlays over it in order, and resolve the result into operations.

Requires the document feature.

Every argument is a file’s contents, YAML or JSON. overlays is a list because corrections come in layers — each one corrects the document the ones before it produced, so the order they are given in is the order they happen. An empty list runs a document that is already corrected.

This is the expensive door, and the document feature is what opens it. A bless step calls it once and writes Document::to_blob beside the rest of what it generates; a shipped binary compiles without the feature and reaches the same reduction through Document::from_blob.

use typed_openapi::{Document, Invocation, Values};

let doc = Document::load(
    include_str!("../tests/fixtures/toy.yaml"),
    &[
        include_str!("../tests/fixtures/corrections.yaml"),
        include_str!("../tests/fixtures/cli.yaml"),
    ],
)?;
let op = doc.get("getVoucher").expect("the document describes it");
let request = Invocation::new(op, Values::new().param("id", 5))?.request(doc.base())?;
assert_eq!(request.uri().path(), "/vouchers/5");

Source

pub fn from_blob(blob: &[u8]) -> Result<Self, DocumentError>

The same reduction, already done and written down.

This is the call a shipped binary makes. Document::load is bless-time work — a YAML parse, an openapiv3 deserialisation and a walk over every path item — and none of it tells a CLI anything that is not already in here. The bytes come from Document::to_blob in the same bless run that wrote the rest of the generated code.

Source

pub fn to_blob(&self) -> Result<Vec<u8>, DocumentError>

This reduction, as the bytes a bless step commits.

The encoding is not self-describing and carries no version tag: it is written and read by one build of one workspace, and an adopter who skips the bless step is caught by the pairing check in Api::new and by the test that reduces the committed document and compares it with this.

Source

pub fn base(&self) -> &Uri

The server the document names first. A caller may override it.

Source

pub fn iter(&self) -> Iter<'_, Operation> ⓘ

Source

pub fn get(&self, operation_id: &str) -> Option<&Operation>

By operationId, as the document spells it. This is the lookup a typed Rust caller uses.

Source

pub fn by_command(&self, group: &str, command: &str) -> Option<&Operation>

By the two names the user types, <group> <command>.

Source

pub fn operations(&self) -> &[Operation]

Every operation, in document order. The order is the one a generated inventory is emitted in, which is what Document::matches checks.

Source

pub fn gates(&self) -> Vec<&Gate>

Every gate any operation in this document names, once each and in document order.

This is the list a --help page, a release note or a test suite reads instead of keeping one by hand: a gate an Overlay adds appears here the moment the document is reduced, and nothing has to be told twice.

Source

pub fn gated_by(&self, gate: &str) -> impl Iterator<Item = &Operation>

Every operation standing behind one gate, in document order.

A suite that has something to say about everything irreversible asks the document which operations those are, rather than carrying a list that an Overlay can silently grow past.

Source

pub fn matches( &self, inventory: &[(&str, &str, &str)], ) -> Result<(), DriftError>

Check this document against a generated (operationId, method, path) inventory, row by row and in order.

A caller that has run this may index Document::operations by the inventory’s own positions: every row named an operation, and every operation was named by a row.