Skip to content

Commit

Permalink
Add serve method fo utoipa-swagger-ui (#65)
Browse files Browse the repository at this point in the history
Add serve method to provide simplier API to serve Swagger UI from frameworks which does not
have default boiler plate implementation available. Previously it was quite tedious serve Swagger UI
via utoipa-swagger-ui with frameworks that does not have default boiler plate implementation.

This also fixes following minor things

* Fix SecurityScheme reference on openapi docs.
* Hide the utoipa-gen generated code from docs.
  • Loading branch information
juhaku authored Apr 7, 2022
1 parent a2e33f2 commit 970bd59
Show file tree
Hide file tree
Showing 8 changed files with 313 additions and 81 deletions.
8 changes: 6 additions & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]
name = "utoipa"
description = "Compile time generated OpenAPI documentation for Rust"
version = "0.1.0"
version = "0.1.1"
edition = "2021"
license = "MIT OR Apache-2.0"
readme = "README.md"
Expand All @@ -10,6 +10,10 @@ keywords = ["rest-api", "openapi", "auto-generate", "documentation", "compile-ti
# homepage = ""
repository = "https://github.com/juhaku/utoipa"
categories = ["web-programming"]
authors = [
"Juha Kukkonen <juha7kukkonen@gmail.com>"
]

exclude = [
".git*",
".github"
Expand All @@ -24,7 +28,7 @@ json = ["serde_json", "utoipa-gen/json"]
[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = { version = "1.0", optional = true }
utoipa-gen = { version = "0.1.0", path = "./utoipa-gen" }
utoipa-gen = { version = "0.1.1", path = "./utoipa-gen" }

[dev-dependencies]
actix-web = { version = "4" }
Expand Down
18 changes: 9 additions & 9 deletions src/openapi/schema.rs
Original file line number Diff line number Diff line change
Expand Up @@ -64,10 +64,10 @@ impl Components {
..Default::default()
}
}
/// Add [`SecuritySchema`] to [`Components`]
/// Add [`SecurityScheme`] to [`Components`]
///
/// Accepts two arguments where first is the name of the [`SecuritySchema`]. This is later when
/// referenced by [`SecurityRequirement`][requirement]s. Second parameter is the [`SecuritySchema`].
/// Accepts two arguments where first is the name of the [`SecurityScheme`]. This is later when
/// referenced by [`SecurityRequirement`][requirement]s. Second parameter is the [`SecurityScheme`].
///
/// [requirement]: ../security/struct.SecurityRequirement.html
pub fn add_security_scheme<N: Into<String>, S: Into<SecurityScheme>>(
Expand All @@ -79,10 +79,10 @@ impl Components {
.insert(name.into(), security_schema.into());
}

/// Add iterator of [`SecuritySchema`]s to [`Components`].
/// Add iterator of [`SecurityScheme`]s to [`Components`].
///
/// Accepts two arguments where first is the name of the [`SecuritySchema`]. This is later when
/// referenced by [`SecurityRequirement`][requirement]s. Second parameter is the [`SecuritySchema`].
/// Accepts two arguments where first is the name of the [`SecurityScheme`]. This is later when
/// referenced by [`SecurityRequirement`][requirement]s. Second parameter is the [`SecurityScheme`].
///
/// [requirement]: ../security/struct.SecurityRequirement.html
pub fn add_security_schemes_from_iter<
Expand Down Expand Up @@ -111,10 +111,10 @@ impl ComponentsBuilder {
self
}

/// Add [`SecuritySchema`] to [`Components`].
/// Add [`SecurityScheme`] to [`Components`].
///
/// Accepts two arguments where first is the name of the [`SecuritySchema`]. This is later when
/// referenced by [`SecurityRequirement`][requirement]s. Second parameter is the [`SecuritySchema`].
/// Accepts two arguments where first is the name of the [`SecurityScheme`]. This is later when
/// referenced by [`SecurityRequirement`][requirement]s. Second parameter is the [`SecurityScheme`].
///
/// [requirement]: ../security/struct.SecurityRequirement.html
pub fn security_schema<N: Into<String>, S: Into<SecurityScheme>>(
Expand Down
28 changes: 14 additions & 14 deletions src/openapi/security.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//! Implements [OpenAPI Security Schema][security] types.
//!
//! Refer to [`SecuritySchema`] for usage and more details.
//! Refer to [`SecurityScheme`] for usage and more details.
//!
//! [security]: https://spec.openapis.org/oas/latest.html#security-scheme-object
use std::{collections::HashMap, iter};
Expand All @@ -11,7 +11,7 @@ use super::{build_fn, builder, from, new};

/// OpenAPI [security requirment][security] object.
///
/// Security requirement holds list of required [`SecuritySchema`] *names* and possible *scopes* required
/// Security requirement holds list of required [`SecurityScheme`] *names* and possible *scopes* required
/// to execute the operation. They can be defined in [`#[utoipa::path(...)]`][path] or in `#[openapi(...)]`
/// of [`OpenApi`][openapi].
///
Expand All @@ -33,9 +33,9 @@ pub struct SecurityRequirement {
impl SecurityRequirement {
/// Construct a new [`SecurityRequirement`]
///
/// Accepts name for the security requirement which must match to the name of available [`SecuritySchema`].
/// Accepts name for the security requirement which must match to the name of available [`SecurityScheme`].
/// Second parameter is [`IntoIterator`] of [`Into<String>`] scopes needed by the [`SecurityRequirement`].
/// Scopes must match to the ones defined in [`SecuritySchema`].
/// Scopes must match to the ones defined in [`SecurityScheme`].
///
/// # Examples
///
Expand Down Expand Up @@ -120,7 +120,7 @@ pub enum SecurityScheme {
},
}

/// Api key authentication [`SecuritySchema`].
/// Api key authentication [`SecurityScheme`].
#[derive(Serialize, Deserialize, Clone)]
#[serde(tag = "in", rename_all = "lowercase")]
#[cfg_attr(feature = "debug", derive(Debug))]
Expand All @@ -141,7 +141,7 @@ pub struct ApiKeyValue {
/// Name of the [`ApiKey`] parameter.
pub name: String,

/// Description of the the [`ApiKey`] [`SecuritySchema`]. Supports markdown syntax.
/// Description of the the [`ApiKey`] [`SecurityScheme`]. Supports markdown syntax.
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
}
Expand Down Expand Up @@ -183,7 +183,7 @@ impl ApiKeyValue {
builder! {
HttpBuilder;

/// Http authentication [`SecuritySchema`] builder.
/// Http authentication [`SecurityScheme`] builder.
///
/// Methods can be chained to configure _bearer_format_ or to add _description_.
#[non_exhaustive]
Expand All @@ -198,7 +198,7 @@ builder! {
#[serde(skip_serializing_if = "Option::is_none")]
pub bearer_format: Option<String>,

/// Optional description of [`Http`] [`SecuritySchema`] supporting markdown syntax.
/// Optional description of [`Http`] [`SecurityScheme`] supporting markdown syntax.
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
}
Expand Down Expand Up @@ -230,7 +230,7 @@ impl HttpBuilder {
///
/// # Examples
///
/// Create new [`Http`] [`SecuritySchema`] via [`HttpBuilder`].
/// Create new [`Http`] [`SecurityScheme`] via [`HttpBuilder`].
/// ```rust
/// # use utoipa::openapi::security::{HttpBuilder, HttpAuthScheme};
/// let http = HttpBuilder::new().scheme(HttpAuthScheme::Basic).build();
Expand Down Expand Up @@ -294,7 +294,7 @@ impl Default for HttpAuthScheme {
}
}

/// Open id connect [`SecuritySchema`]
/// Open id connect [`SecurityScheme`]
#[non_exhaustive]
#[derive(Serialize, Deserialize, Clone)]
#[serde(rename_all = "camelCase")]
Expand All @@ -303,7 +303,7 @@ pub struct OpenIdConnect {
/// Url of the [`OpenIdConnect`] to discover OAuth2 connect values.
pub open_id_connect_url: String,

/// Description of [`OpenIdConnect`] [`SecuritySchema`] supporting markdown syntax.
/// Description of [`OpenIdConnect`] [`SecurityScheme`] supporting markdown syntax.
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
}
Expand All @@ -324,7 +324,7 @@ impl OpenIdConnect {
}
}

/// Construct a new [`OpenIdConnect`] [`SecuritySchema`] with optional description
/// Construct a new [`OpenIdConnect`] [`SecurityScheme`] with optional description
/// supporting markdown syntax.
///
/// # Examples
Expand All @@ -341,15 +341,15 @@ impl OpenIdConnect {
}
}

/// OAuth2 [`Flow`] configuration for [`SecuritySchema`].
/// OAuth2 [`Flow`] configuration for [`SecurityScheme`].
#[non_exhaustive]
#[derive(Serialize, Deserialize, Clone)]
#[cfg_attr(feature = "debug", derive(Debug))]
pub struct OAuth2 {
/// Map of supported OAuth2 flows.
pub flows: HashMap<String, Flow>,

/// Optional description for the [`OAuth2`] [`Flow`] [`SecuritySchema`].
/// Optional description for the [`OAuth2`] [`Flow`] [`SecurityScheme`].
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
}
Expand Down
5 changes: 4 additions & 1 deletion utoipa-gen/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
[package]
name = "utoipa-gen"
description = "Code generation implementation for utoipa"
version = "0.1.0"
version = "0.1.1"
edition = "2021"
license = "MIT OR Apache-2.0"
readme = "README.md"
keywords = ["openapi", "codegen", "proc-macro", "documentation", "compile-time"]
repository = "https://github.com/juhaku/utoipa"
authors = [
"Juha Kukkonen <juha7kukkonen@gmail.com>"
]

[lib]
proc-macro = true
Expand Down
1 change: 1 addition & 0 deletions utoipa-gen/src/path.rs
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,7 @@ impl ToTokens for Path {

tokens.extend(quote! {
#[allow(non_camel_case_types)]
#[doc(hidden)]
pub struct #path_struct;

impl utoipa::Path for #path_struct {
Expand Down
7 changes: 5 additions & 2 deletions utoipa-swagger-ui/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
[package]
name = "utoipa-swagger-ui"
description = "Swagger UI for utoipa"
version = "0.1.2"
version = "0.2.0"
edition = "2021"
license = "MIT OR Apache-2.0"
readme = "README.md"
keywords = ["swagger-ui", "openapi", "documentation"]
repository = "https://github.com/juhaku/utoipa"
categories = ["web-programming"]
authors = [
"Juha Kukkonen <juha7kukkonen@gmail.com>"
]

[features]
debug = []
Expand All @@ -16,7 +19,7 @@ debug = []
rust-embed = { version = "6.3", features = ["interpolate-folder-path"] }
mime_guess = { version = "2.0" }
actix-web = { version = "4", optional = true }
utoipa = { version = "0.1.0", path = "..", default-features = false, features = [] }
utoipa = { version = "0.1.1", path = "..", default-features = false, features = [] }

[package.metadata.docs.rs]
features = ["actix-web"]
Expand Down
2 changes: 1 addition & 1 deletion utoipa-swagger-ui/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ HttpServer::new(move || {
.url("/api-doc/openapi.json", ApiDoc::openapi()),
)
})
.bind(format!("{}:{}", Ipv4Addr::UNSPECIFIED, 8989)).unwrap()
.bind((Ipv4Addr::UNSPECIFIED, 8989)).unwrap()
.run();
```
**actix-web** feature need to be enabled.
Expand Down
Loading

0 comments on commit 970bd59

Please sign in to comment.