diff --git a/progenitor-client/src/lib.rs b/progenitor-client/src/lib.rs index 8675045..f7ca0f6 100644 --- a/progenitor-client/src/lib.rs +++ b/progenitor-client/src/lib.rs @@ -1,5 +1,9 @@ // Copyright 2022 Oxide Computer Company +//! Support for generated clients. + +#![deny(missing_docs)] + mod progenitor_client; pub use crate::progenitor_client::*; diff --git a/progenitor-client/src/progenitor_client.rs b/progenitor-client/src/progenitor_client.rs index 742f8a6..d1e0ca5 100644 --- a/progenitor-client/src/progenitor_client.rs +++ b/progenitor-client/src/progenitor_client.rs @@ -401,6 +401,7 @@ const PATH_SET: &percent_encoding::AsciiSet = &percent_encoding::CONTROLS .add(b'%'); #[doc(hidden)] +/// Percent encode input string. pub fn encode_path(pc: &str) -> String { percent_encoding::utf8_percent_encode(pc, PATH_SET).to_string() } diff --git a/progenitor-impl/src/lib.rs b/progenitor-impl/src/lib.rs index acf8658..ed3af18 100644 --- a/progenitor-impl/src/lib.rs +++ b/progenitor-impl/src/lib.rs @@ -1,7 +1,10 @@ // Copyright 2024 Oxide Computer Company -use std::collections::BTreeMap; -use std::collections::{HashMap, HashSet}; +//! Core implementation for the progenitor OpenAPI client generator. + +#![deny(missing_docs)] + +use std::collections::{BTreeMap, HashMap, HashSet}; use openapiv3::OpenAPI; use proc_macro2::TokenStream; @@ -22,6 +25,7 @@ mod template; mod to_schema; mod util; +#[allow(missing_docs)] #[derive(Error, Debug)] pub enum Error { #[error("unexpected value type {0}: {1}")] @@ -38,8 +42,10 @@ pub enum Error { InternalError(String), } +#[allow(missing_docs)] pub type Result = std::result::Result; +/// OpenAPI generator. pub struct Generator { type_space: TypeSpace, settings: GenerationSettings, @@ -47,6 +53,7 @@ pub struct Generator { uses_websockets: bool, } +/// Settings for [Generator]. #[derive(Default, Clone)] pub struct GenerationSettings { interface: InterfaceStyle, @@ -61,9 +68,12 @@ pub struct GenerationSettings { convert: Vec<(schemars::schema::SchemaObject, String, Vec)>, } +/// Style of generated client. #[derive(Clone, Deserialize, PartialEq, Eq)] pub enum InterfaceStyle { + /// Use positional style. Positional, + /// Use builder style. Builder, } @@ -73,9 +83,12 @@ impl Default for InterfaceStyle { } } +/// Style for using the OpenAPI tags when generating names in the client. #[derive(Clone, Deserialize)] pub enum TagStyle { + /// Merge tags to create names in the generated client. Merged, + /// Use each tag name to create separate names in the generated client. Separate, } @@ -86,40 +99,49 @@ impl Default for TagStyle { } impl GenerationSettings { + /// Create new generator settings with default values. pub fn new() -> Self { Self::default() } + /// Set the [InterfaceStyle]. pub fn with_interface(&mut self, interface: InterfaceStyle) -> &mut Self { self.interface = interface; self } + /// Set the [TagStyle]. pub fn with_tag(&mut self, tag: TagStyle) -> &mut Self { self.tag = tag; self } + /// Client inner type available to pre and post hooks. pub fn with_inner_type(&mut self, inner_type: TokenStream) -> &mut Self { self.inner_type = Some(inner_type); self } + /// Hook invoked before issuing the HTTP request. pub fn with_pre_hook(&mut self, pre_hook: TokenStream) -> &mut Self { self.pre_hook = Some(pre_hook); self } + /// Hook invoked prior to receiving the HTTP response. pub fn with_post_hook(&mut self, post_hook: TokenStream) -> &mut Self { self.post_hook = Some(post_hook); self } + /// Additional derive macros applied to generated types. pub fn with_derive(&mut self, derive: impl ToString) -> &mut Self { self.extra_derives.push(derive.to_string()); self } + /// Modify a type with the given name. + /// See [typify::TypeSpaceSettings::with_patch]. pub fn with_patch>( &mut self, type_name: S, @@ -130,6 +152,8 @@ impl GenerationSettings { self } + /// Replace a referenced type with a named type. + /// See [typify::TypeSpaceSettings::with_replacement]. pub fn with_replacement< TS: ToString, RS: ToString, @@ -147,6 +171,8 @@ impl GenerationSettings { self } + /// Replace a given schema with a named type. + /// See [typify::TypeSpaceSettings::with_conversion]. pub fn with_conversion>( &mut self, schema: schemars::schema::SchemaObject, @@ -173,6 +199,7 @@ impl Default for Generator { } impl Generator { + /// Create a new generator with default values. pub fn new(settings: &GenerationSettings) -> Self { let mut type_settings = TypeSpaceSettings::default(); type_settings @@ -211,6 +238,7 @@ impl Generator { } } + /// Emit a [TokenStream] containing the generated client code. pub fn generate_tokens(&mut self, spec: &OpenAPI) -> Result { validate_openapi(spec)?; @@ -522,22 +550,24 @@ impl Generator { Ok(out) } - // TODO deprecate? + /// Get the [TypeSpace] for schemas present in the OpenAPI specification. pub fn get_type_space(&self) -> &TypeSpace { &self.type_space } + /// Whether the generated client needs to use additional crates to support futures. pub fn uses_futures(&self) -> bool { self.uses_futures } + /// Whether the generated client needs to use additional crates to support websockets. pub fn uses_websockets(&self) -> bool { self.uses_websockets } } +/// Add newlines after end-braces at <= two levels of indentation. pub fn space_out_items(content: String) -> Result { - // Add newlines after end-braces at <= two levels of indentation. Ok(if cfg!(not(windows)) { let regex = regex::Regex::new(r#"(\n\s*})(\n\s{0,8}[^} ])"#).unwrap(); regex.replace_all(&content, "$1\n$2").to_string() diff --git a/progenitor-macro/src/lib.rs b/progenitor-macro/src/lib.rs index 5231d81..256e24d 100644 --- a/progenitor-macro/src/lib.rs +++ b/progenitor-macro/src/lib.rs @@ -1,5 +1,9 @@ // Copyright 2022 Oxide Computer Company +//! Macros for the progenitor OpenAPI client generator. + +#![deny(missing_docs)] + use std::{ collections::HashMap, fmt::Display, diff --git a/progenitor/src/lib.rs b/progenitor/src/lib.rs index a024b1b..8416e44 100644 --- a/progenitor/src/lib.rs +++ b/progenitor/src/lib.rs @@ -10,6 +10,8 @@ //! For details see the [repo //! README](https://github.com/oxidecomputer/progenitor/blob/main/README.md) +#![deny(missing_docs)] + pub use progenitor_client; pub use progenitor_impl::Error; pub use progenitor_impl::GenerationSettings;