Struct Document 

pub struct Document {
    pub openapi: String,
    pub self_uri: Option<String>,
    pub info: Info,
    pub json_schema_dialect: Option<String>,
    pub servers: Vec<Server>,
    pub paths: Paths,
    pub webhooks: Map<PathItem>,
    pub components: Components,
    pub security: Vec<SecurityRequirement>,
    pub tags: Vec<Tag>,
    pub external_docs: Option<ExternalDocumentation>,
    pub extensions: Extensions,
}

A complete OpenAPI description.

Fields

openapi: String

The version of the OpenAPI Specification this document uses.

self_uri: Option<String>

The canonical URI of this document.

Introduced in OpenAPI 3.2. When present it is the base URI that references resolve against, which is what makes a $ref between two separately-served documents interoperable.

info: Info

Metadata about the API.

json_schema_dialect: Option<String>

The default JSON Schema dialect for schemas in this document.

Defaults to OAS_DIALECT when absent. Note that 3.1 and 3.2 share one dialect URI, so this does not vary by specification version.

servers: Vec<Server>

The servers providing the API.

paths: Paths

The available paths and operations.

Always written, even when empty. Every version Kynos emits requires a document to carry at least one of paths, components or webhooks, and this is the one of the three that is always true of an API: an empty Paths Object says there are no operations to show, which the specification’s “Security Filtering” section blesses in as many words. Skipping it is what let a description of nothing but opaque routes – which take no paths key by design – emit as a document declaring nothing at all.

webhooks: Map<PathItem>

Webhooks the API delivers, keyed by a name of the API’s choosing.

Unlike paths, these are requests the API makes, initiated outside any single operation.

components: Components

Reusable objects.

security: Vec<SecurityRequirement>

The security requirements applying across the API.

An operation may override this; an operation with an empty override is anonymous.

tags: Vec<Tag>

Metadata for the tags operations use. Names must be unique.

external_docs: Option<ExternalDocumentation>

Additional external documentation.

extensions: Extensions

Specification extensions.

Implementations

impl Document

pub fn is_authoritative(&self) -> bool

Whether every operation and route in this document is verifiably described.

This is the property NOT_AUTHORITATIVE_ANNOTATION negates. Computing it rather than reading the stamp is deliberate: the stamp is a summary a consumer reads, not the fact itself. An annotation this build cannot read counts as unclean, because the alternative is calling a description authoritative on the strength of not understanding it.

pub fn restamp_authority(&mut self)

Brings NOT_AUTHORITATIVE_ANNOTATION into line with this document.

Adds the stamp when something is opaque and removes it when nothing is, so that a document edited after the fact cannot keep a stamp it no longer earns — or lose one it does.

impl Document

pub fn to_json(&self) -> Result<String, Error>

Serializes to pretty-printed JSON.

Errors

Returns an error only if a specification extension holds a value that cannot be represented in JSON.

pub fn to_yaml(&self) -> Result<String, Error>

Serializes to YAML.

Errors

Returns an error only if a number cannot be written as a YAML number: either it is beyond the range of a 64-bit float, or a value holds an object shaped like serde_json’s private number token whose string is no number at all. Both can happen only when serde_json’s arbitrary_precision feature is unified into the build: without it, serde_json holds no such number, and gives that key no meaning.

pub fn emit(&self, version: SpecVersion) -> Result<Self, SpecError>

Produces this document as version, refusing a lossy downgrade.

Cargo unifies features across a dependency graph, so a program can find itself built with openapi32 enabled even when it needs to publish a 3.1 description. This is the safe way to ask for one: rather than dropping 3.2-only constructs and emitting something that misdescribes the API, it fails and names what stands in the way.

Errors

Returns SpecError::RequiresV3_2 when the document uses a construct that version cannot express.

impl Document

pub fn new(version: SpecVersion, info: Info) -> Self

Creates a document targeting version.

pub fn spec_version(&self) -> Option<SpecVersion>

The specification version this document declares.

Returns None when openapi holds a version this build does not model — a 3.2 document read by a 3.1-only build, most often.

pub fn effective_dialect(&self) -> &str

The dialect schemas in this document default to.

pub fn with_server(self, server: Server) -> Self

Adds a server.

pub fn with_tag(self, tag: Tag) -> Self

Adds tag metadata.

pub fn with_security(self, requirement: SecurityRequirement) -> Self

Adds a document-wide security requirement.

impl Document

pub fn validate(&self, version: SpecVersion) -> Result<(), Vec<Violation>>

Validates this document against the rules of version.

Errors

Returns every Severity::Error violation found. Warnings are discarded; use Validator::validate to see them.

Trait Implementations

impl Clone for Document

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Document

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Document

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Document

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Document

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Document

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Document