Add crate for serving Scalar via utoipa (#892)

This is a PR for adding [Scalar](https://scalar.com/) API visualization to the utoipa ecosystem. Scalar is yet another web application for OpenAPI specifications, but I prefer it over Redoc/Rapidoc since it shows the model types too! Most of the things here were mimicked after the Redoc PR (#720). - The crate has been added to the CI/publish/test scripts - The todo-axum/todo-actix/todo-rocket examples now serve Scalar too under /scalar - The crate has been implemented for axum, actix-web, and rocket
juhaku · May 1, 2024 · 613b3ad · 613b3ad
1 parent 5aa9749
commit 613b3ad
Show file tree

Hide file tree

Showing 23 changed files with 711 additions and 4 deletions.
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -23,6 +23,7 @@ jobs:
           - utoipa-swagger-ui
           - utoipa-redoc
           - utoipa-rapidoc
+          - utoipa-scalar
       fail-fast: true
     runs-on: ubuntu-latest
 
@@ -56,6 +57,8 @@ jobs:
               changes=true
             elif [[ "$change" == "utoipa-rapidoc" && "${{ matrix.crate }}" == "utoipa-rapidoc" && $changes == false ]]; then
               changes=true
+            elif [[ "$change" == "utoipa-scalar" && "${{ matrix.crate }}" == "utoipa-scalar" && $changes == false ]]; then
+              changes=true
             fi
           done < <(git diff --name-only ${{ github.sha }}~ ${{ github.sha }} | grep .rs | awk -F \/ '{print $1}')
           echo "${{ matrix.crate }} changes: $changes"

diff --git a/.github/workflows/draft.yaml b/.github/workflows/draft.yaml
@@ -18,6 +18,7 @@ jobs:
           - utoipa-swagger-ui
           - utoipa-redoc
           - utoipa-rapidoc
+          - utoipa-scalar
     runs-on: ubuntu-latest
 
     steps:

diff --git a/Cargo.toml b/Cargo.toml
@@ -6,6 +6,7 @@ members = [
     "utoipa-swagger-ui",
     "utoipa-redoc",
     "utoipa-rapidoc",
+    "utoipa-scalar",
 ]
 
 [workspace.metadata.publish]
@@ -15,4 +16,5 @@ order = [
     "utoipa-swagger-ui",
     "utoipa-redoc",
     "utoipa-rapidoc",
+    "utoipa-scalar",
 ]
diff --git a/examples/README.md b/examples/README.md
@@ -8,5 +8,5 @@ All examples have their own README.md, and can be seen using two steps:
 1. Run `cargo run`
 2. Browse to `http://localhost:8080/swagger-ui/` or `http://localhost:8080/redoc` or `http://localhost:8080/rapidoc`.
 
-`Todo-actix`, `todo-axum` and `rocket-todo` have Swagger UI, Redoc and RapiDoc setup, others have Swagger UI 
+`todo-actix`, `todo-axum` and `rocket-todo` have Swagger UI, Redoc, RapiDoc, and Scalar setup, others have Swagger UI 
 if not explicitly stated otherwise.
diff --git a/examples/rocket-todo/Cargo.toml b/examples/rocket-todo/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "rocket-todo"
-description = "Simple rocket todo example api with utoipa and Swagger UI and Redoc"
+description = "Simple rocket todo example api with utoipa and Swagger UI, Rapidoc, Redoc, and Scalar"
 version = "0.1.0"
 edition = "2021"
 license = "MIT"
@@ -14,6 +14,7 @@ utoipa = { path = "../../utoipa", features = ["rocket_extras"] }
 utoipa-swagger-ui = { path = "../../utoipa-swagger-ui", features = ["rocket"] }
 utoipa-redoc = { path = "../../utoipa-redoc", features = ["rocket"] }
 utoipa-rapidoc = { path = "../../utoipa-rapidoc", features = ["rocket"] }
+utoipa-scalar = { path = "../../utoipa-scalar", features = ["rocket"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 env_logger = "0.10.0"

diff --git a/examples/rocket-todo/README.md b/examples/rocket-todo/README.md
@@ -11,6 +11,8 @@ If you prefer Redoc just head to `http://localhost:8000/redoc` and view the Open
 
 RapiDoc can be found from `http://localhost:8000/redoc`.
 
+Scalar can be reached on `http://localhost:8000/scalar`.
+
 ```bash
 cargo run
 ```

diff --git a/examples/rocket-todo/src/main.rs b/examples/rocket-todo/src/main.rs
@@ -7,6 +7,7 @@ use utoipa::{
 };
 use utoipa_rapidoc::RapiDoc;
 use utoipa_redoc::{Redoc, Servable};
+use utoipa_scalar::{Scalar, Servable as ScalarServable};
 use utoipa_swagger_ui::SwaggerUi;
 
 use crate::todo::TodoStore;
@@ -62,6 +63,7 @@ fn rocket() -> Rocket<Build> {
         //     RapiDoc::with_openapi("/api-docs/openapi2.json", ApiDoc::openapi()).path("/rapidoc")
         // )
         .mount("/", Redoc::with_url("/redoc", ApiDoc::openapi()))
+        .mount("/", Scalar::with_url("/scalar", ApiDoc::openapi()))
         .mount(
             "/todo",
             routes![

diff --git a/examples/todo-actix/Cargo.toml b/examples/todo-actix/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "todo-actix"
-description = "Simple actix-web todo example api with utoipa and Swagger UI and Redoc"
+description = "Simple actix-web todo example api with utoipa and Swagger UI, Rapidoc, Redoc, and Scalar"
 version = "0.1.0"
 edition = "2021"
 license = "MIT"
@@ -21,5 +21,6 @@ utoipa = { path = "../../utoipa", features = ["actix_extras"] }
 utoipa-swagger-ui = { path = "../../utoipa-swagger-ui", features = ["actix-web"] }
 utoipa-redoc = { path = "../../utoipa-redoc", features = ["actix-web"] }
 utoipa-rapidoc = { path = "../../utoipa-rapidoc", features = ["actix-web"] }
+utoipa-scalar = { path = "../../utoipa-scalar", features = ["actix-web"] }
 
 [workspace]
diff --git a/examples/todo-actix/README.md b/examples/todo-actix/README.md
@@ -11,6 +11,8 @@ If you prefer Redoc just head to `http://localhost:8080/redoc` and view the Open
 
 RapiDoc can be found from `http://localhost:8080/rapidoc`.
 
+Scalar can be reached on `http://localhost:8080/scalar`.
+
 ```bash
 cargo run
 ```

diff --git a/examples/todo-actix/src/main.rs b/examples/todo-actix/src/main.rs
@@ -17,6 +17,7 @@ use utoipa::{
 };
 use utoipa_rapidoc::RapiDoc;
 use utoipa_redoc::{Redoc, Servable};
+use utoipa_scalar::{Scalar, Servable as ScalarServable};
 use utoipa_swagger_ui::SwaggerUi;
 
 use crate::todo::{ErrorResponse, TodoStore};
@@ -81,6 +82,7 @@ async fn main() -> Result<(), impl Error> {
             // If we wanted to serve the schema, the following would work:
             // .service(RapiDoc::with_openapi("/api-docs/openapi2.json", openapi.clone()).path("/rapidoc"))
             .service(RapiDoc::new("/api-docs/openapi.json").path("/rapidoc"))
+            .service(Scalar::with_url("/scalar", openapi.clone()))
     })
     .bind((Ipv4Addr::UNSPECIFIED, 8080))?
     .run()

diff --git a/examples/todo-axum/Cargo.toml b/examples/todo-axum/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "todo-axum"
-description = "Simple axum todo example api with utoipa and Swagger UI and Redoc"
+description = "Simple axum todo example api with utoipa and Swagger UI, Rapidoc, Redoc, and Scalar"
 version = "0.1.0"
 edition = "2021"
 license = "MIT"
@@ -19,6 +19,7 @@ utoipa = { path = "../../utoipa", features = ["axum_extras"] }
 utoipa-swagger-ui = { path = "../../utoipa-swagger-ui", features = ["axum"] }
 utoipa-redoc = { path = "../../utoipa-redoc", features = ["axum"] }
 utoipa-rapidoc = { path = "../../utoipa-rapidoc", features = ["axum"] }
+utoipa-scalar = { path = "../../utoipa-scalar", features = ["axum"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 env_logger = "0.10.0"

diff --git a/examples/todo-axum/README.md b/examples/todo-axum/README.md
@@ -11,6 +11,8 @@ If you prefer Redoc just head to `http://localhost:8080/redoc` and view the Open
 
 RapiDoc can be found from `http://localhost:8080/rapidoc`.
 
+Scalar can be reached on `http://localhost:8080/scalar`.
+
 ```bash
 cargo run
 ```

diff --git a/examples/todo-axum/src/main.rs b/examples/todo-axum/src/main.rs
@@ -12,6 +12,7 @@ use utoipa::{
 };
 use utoipa_rapidoc::RapiDoc;
 use utoipa_redoc::{Redoc, Servable};
+use utoipa_scalar::{Scalar, Servable as ScalarServable};
 use utoipa_swagger_ui::SwaggerUi;
 
 use crate::todo::Store;
@@ -59,6 +60,7 @@ async fn main() -> Result<(), Error> {
         .merge(RapiDoc::new("/api-docs/openapi.json").path("/rapidoc"))
         // Alternative to above
         // .merge(RapiDoc::with_openapi("/api-docs/openapi2.json", ApiDoc::openapi()).path("/rapidoc"))
+        .merge(Scalar::with_url("/scalar", ApiDoc::openapi()))
         .route(
             "/todo",
             routing::get(todo::list_todos).post(todo::create_todo),

diff --git a/scripts/test.sh b/scripts/test.sh
@@ -29,5 +29,7 @@ for crate in $crates; do
         $CARGO test -p utoipa-redoc --features actix-web,rocket,axum
     elif [[ "$crate" == "utoipa-rapidoc" ]]; then
         $CARGO test -p utoipa-rapidoc --features actix-web,rocket,axum
+    elif [[ "$crate" == "utoipa-scalar" ]]; then
+        $CARGO test -p utoipa-scalar --features actix-web,rocket,axum
     fi
 done
diff --git a/utoipa-scalar/Cargo.toml b/utoipa-scalar/Cargo.toml
@@ -0,0 +1,23 @@
+[package]
+name = "utoipa-scalar"
+description = "Scalar for utoipa"
+version = "3.0.0"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+readme = "README.md"
+keywords = ["scalar", "openapi", "documentation"]
+repository = "https://github.com/juhaku/utoipa"
+categories = ["web-programming"]
+authors = ["Juha Kukkonen <juha7kukkonen@gmail.com>"]
+
+[package.metadata.docs.rs]
+features = ["actix-web", "axum", "rocket"]
+rustdoc-args = ["--cfg", "doc_cfg"]
+
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = { version = "1.0" }
+utoipa = { version = "4", path = "../utoipa" }
+actix-web = { version = "4", optional = true, default-features = false }
+rocket = { version = "0.5", features = ["json"], optional = true }
+axum = { version = "0.7", default-features = false, optional = true }
-Original file line number
+Diff line change
@@ Expand Up @@
     RapiDoc can be found from `http://localhost:8000/redoc`.
+    Scalar can be reached on `http://localhost:8000/scalar`.
     ```bash
     cargo run
     ```
@@ Expand Down @@