Add serve method fo utoipa-swagger-ui (#65)

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.
juhaku · Apr 7, 2022 · 970bd59 · 970bd59
1 parent a2e33f2
commit 970bd59
Show file tree

Hide file tree

Showing 8 changed files with 313 additions and 81 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -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"
@@ -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"
@@ -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" }

diff --git a/src/openapi/schema.rs b/src/openapi/schema.rs
@@ -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>>(
@@ -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<
@@ -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>>(

diff --git a/src/openapi/security.rs b/src/openapi/security.rs
@@ -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};
@@ -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].
 ///
@@ -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
     ///
@@ -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))]
@@ -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>,
 }
@@ -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]
@@ -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>,
     }
@@ -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();
@@ -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")]
@@ -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>,
 }
@@ -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
@@ -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>,
 }

diff --git a/utoipa-gen/Cargo.toml b/utoipa-gen/Cargo.toml
@@ -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

diff --git a/utoipa-gen/src/path.rs b/utoipa-gen/src/path.rs
@@ -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 {

diff --git a/utoipa-swagger-ui/Cargo.toml b/utoipa-swagger-ui/Cargo.toml
@@ -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 = []
@@ -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"]

diff --git a/utoipa-swagger-ui/README.md b/utoipa-swagger-ui/README.md
@@ -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.