Add redoc support for utoipa. (#720)

Create new utoipa-redoc create and add simple redoc implementation. Add redoc service support for actix-web, axum and rocket. Add new warp-todo-redoc example to demonstarte utoipa-redoc in standalone without pre-existing web framework integration. Add CI setup for utoipa-redoc.
juhaku · Aug 6, 2023 · 6baa9b0 · 6baa9b0
1 parent a9f4797
commit 6baa9b0
Show file tree

Hide file tree

Showing 29 changed files with 1,085 additions and 17 deletions.
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -21,6 +21,7 @@ jobs:
           - utoipa
           - utoipa-gen
           - utoipa-swagger-ui
+          - utoipa-redoc
       fail-fast: true
     runs-on: ubuntu-latest
 
@@ -50,6 +51,8 @@ jobs:
               changes=true
             elif [[ "$change" == "utoipa" && "${{ matrix.crate }}" == "utoipa" && $changes == false ]]; then
               changes=true
+            elif [[ "$change" == "utoipa-redoc" && "${{ matrix.crate }}" == "utoipa-redoc" && $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
@@ -16,6 +16,7 @@ jobs:
           - utoipa
           - utoipa-gen
           - utoipa-swagger-ui
+          - utoipa-redoc
     runs-on: ubuntu-latest
 
     steps:

diff --git a/Cargo.toml b/Cargo.toml
@@ -1,10 +1,6 @@
 [workspace]
 resolver = "2"
-members = [
-  "utoipa",
-  "utoipa-gen",
-  "utoipa-swagger-ui",
-]
+members = ["utoipa", "utoipa-gen", "utoipa-swagger-ui", "utoipa-redoc"]
 
 [workspace.metadata.publish]
-order = ["utoipa-gen", "utoipa", "utoipa-swagger-ui"]
+order = ["utoipa-gen", "utoipa", "utoipa-swagger-ui", "utoipa-redoc"]
diff --git a/README.md b/README.md
@@ -37,7 +37,7 @@ Refer to the existing [examples](./examples) for building the "todo" app in the
 - **[tide](https://github.com/http-rs/tide)**
 - **[rocket](https://github.com/SergioBenitez/Rocket)** (`0.4` and `0.5.0-rc3`)
 
-All examples include a [Swagger-UI](https://github.com/swagger-api/swagger-ui).
+All examples include a [Swagger-UI](https://github.com/swagger-api/swagger-ui) or [Redoc](https://github.com/Redocly/redoc).
 
 There are also examples of building multiple OpenAPI docs in one application, each separated in Swagger UI.
 These examples exist only for the **actix** and **warp** frameworks.

diff --git a/examples/README.md b/examples/README.md
@@ -6,4 +6,7 @@ with the library.
 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/`.
+2. Browse to `http://localhost:8080/swagger-ui/` or `http://localhost:8080/redoc`.
+
+`Todo-actix`, `todo-axum` and `rocket-todo` has both Swagger UI and Redoc 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,19 +1,18 @@
 [package]
 name = "rocket-todo"
-description = "Simple rocket todo example api with utoipa and Swagger UI"
+description = "Simple rocket todo example api with utoipa and Swagger UI and Redoc"
 version = "0.1.0"
 edition = "2021"
 license = "MIT"
-authors = [
-  "Elli Example <example@example.com>"
-]
+authors = ["Elli Example <example@example.com>"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
 rocket = { version = "0.5.0-rc.3", features = ["json"] }
 utoipa = { path = "../../utoipa", features = ["rocket_extras"] }
 utoipa-swagger-ui = { path = "../../utoipa-swagger-ui", features = ["rocket"] }
+utoipa-redoc = { path = "../../utoipa-redoc", 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
@@ -1,4 +1,4 @@
-# todo-rocket ~ utoipa with utoipa-swagger-ui example
+# todo-rocket ~ utoipa with utoipa-swagger-ui and utoipa-redoc example
 
 This is a demo `rocket` application with in-memory storage to manage Todo items. The API
 demonstrates `utoipa` with `utoipa-swagger-ui` functionalities.
@@ -7,6 +7,8 @@ For security restricted endpoints the super secret API key is: `utoipa-rocks`.
 
 Just run command below to run the demo application and browse to `http://localhost:8000/swagger-ui/`.
 
+If you prefer Redoc just head to `http://localhost:8000/redoc` and view the Open API.
+
 ```bash
 cargo run
 ```

diff --git a/examples/rocket-todo/src/main.rs b/examples/rocket-todo/src/main.rs
@@ -5,6 +5,7 @@ use utoipa::{
     openapi::security::{ApiKey, ApiKeyValue, SecurityScheme},
     Modify, OpenApi,
 };
+use utoipa_redoc::{Redoc, Servable};
 use utoipa_swagger_ui::SwaggerUi;
 
 use crate::todo::TodoStore;
@@ -51,6 +52,7 @@ fn rocket() -> Rocket<Build> {
             "/",
             SwaggerUi::new("/swagger-ui/<_..>").url("/api-docs/openapi.json", ApiDoc::openapi()),
         )
+        .mount("/", Redoc::with_url("/redoc", 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"
+description = "Simple actix-web todo example api with utoipa and Swagger UI and Redoc"
 version = "0.1.0"
 edition = "2021"
 license = "MIT"
@@ -19,5 +19,6 @@ log = "0.4"
 futures = "0.3"
 utoipa = { path = "../../utoipa", features = ["actix_extras"] }
 utoipa-swagger-ui = { path = "../../utoipa-swagger-ui", features = ["actix-web"] }
+utoipa-redoc = { path = "../../utoipa-redoc", features = ["actix-web"] }
 
 [workspace]
diff --git a/examples/todo-actix/README.md b/examples/todo-actix/README.md
@@ -1,4 +1,4 @@
-# todo-actix ~ utoipa with utoipa-swagger-ui example
+# todo-actix ~ utoipa with utoipa-swagger-ui and utoipa-redoc example
 
 This is a demo `actix-web` application with in-memory storage to manage Todo items. The API
 demonstrates `utoipa` with `utoipa-swagger-ui` functionalities.
@@ -7,6 +7,8 @@ For security restricted endpoints the super secret API key is: `utoipa-rocks`.
 
 Just run command below to run the demo application and browse to `http://localhost:8080/swagger-ui/`.
 
+If you prefer Redoc just head to `http://localhost:8000/redoc` and view the Open API.
+
 ```bash
 cargo run
 ```

diff --git a/examples/todo-actix/src/main.rs b/examples/todo-actix/src/main.rs
@@ -15,6 +15,7 @@ use utoipa::{
     openapi::security::{ApiKey, ApiKeyValue, SecurityScheme},
     Modify, OpenApi,
 };
+use utoipa_redoc::{Redoc, Servable};
 use utoipa_swagger_ui::SwaggerUi;
 
 use crate::todo::{ErrorResponse, TodoStore};
@@ -69,6 +70,7 @@ async fn main() -> Result<(), impl Error> {
         App::new()
             .wrap(Logger::default())
             .configure(todo::configure(store.clone()))
+            .service(Redoc::with_url("/redoc", openapi.clone()))
             .service(
                 SwaggerUi::new("/swagger-ui/{_:.*}").url("/api-docs/openapi.json", openapi.clone()),
             )

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"
+description = "Simple axum todo example api with utoipa and Swagger UI and Redoc"
 version = "0.1.0"
 edition = "2021"
 license = "MIT"
@@ -17,6 +17,7 @@ tokio = { version = "1.17", features = ["full"] }
 tower = "0.4"
 utoipa = { path = "../../utoipa", features = ["axum_extras"] }
 utoipa-swagger-ui = { path = "../../utoipa-swagger-ui", features = ["axum"] }
+utoipa-redoc = { path = "../../utoipa-redoc", 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
@@ -1,4 +1,4 @@
-# todo-axum ~ utoipa with utoipa-swagger-ui example
+# todo-axum ~ utoipa with utoipa-swagger-ui and utoipa-redoc example
 
 This is a demo `axum` application with in-memory storage to manage Todo items. The API
 demonstrates `utoipa` with `utoipa-swagger-ui` functionalities.
@@ -7,6 +7,8 @@ For security restricted endpoints the super secret API key is: `utoipa-rocks`.
 
 Just run command below to run the demo application and browse to `http://localhost:8080/swagger-ui/`.
 
+If you prefer Redoc just head to `http://localhost:8000/redoc` and view the Open API.
+
 ```bash
 cargo run
 ```

diff --git a/examples/todo-axum/src/main.rs b/examples/todo-axum/src/main.rs
@@ -9,6 +9,7 @@ use utoipa::{
     openapi::security::{ApiKey, ApiKeyValue, SecurityScheme},
     Modify, OpenApi,
 };
+use utoipa_redoc::{Redoc, Servable};
 use utoipa_swagger_ui::SwaggerUi;
 
 use crate::todo::Store;
@@ -50,6 +51,7 @@ async fn main() -> Result<(), Error> {
     let store = Arc::new(Store::default());
     let app = Router::new()
         .merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", ApiDoc::openapi()))
+        .merge(Redoc::with_url("/redoc", ApiDoc::openapi()))
         .route(
             "/todo",
             routing::get(todo::list_todos).post(todo::create_todo),

diff --git a/examples/todo-warp-redoc-with-file-config/Cargo.toml b/examples/todo-warp-redoc-with-file-config/Cargo.toml
@@ -0,0 +1,22 @@
+[package]
+name = "todo-warp-redoc-with-file-config"
+description = "Simple warp todo example api with utoipa and utoipa-redoc"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+authors = ["Elli Example <example@example.com>"]
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+tokio = { version = "1", features = ["full"] }
+warp = "0.3"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+env_logger = "0.10.0"
+log = "0.4"
+futures = "0.3"
+utoipa = { path = "../../utoipa" }
+utoipa-redoc = { path = "../../utoipa-redoc" }
+
+[workspace]
diff --git a/examples/todo-warp-redoc-with-file-config/README.md b/examples/todo-warp-redoc-with-file-config/README.md
@@ -0,0 +1,27 @@
+# todo-warp-redoc-with-file-config ~ utoipa with utoipa-redoc example
+
+This is a demo `warp` application with in-memory storage to manage Todo items.
+
+This example is more bare minimum compared to `todo-actix`, since similarly same macro syntax is
+supported, no matter the framework.
+
+
+This how `utoipa-redoc` can be used as standalone without pre-existing framework integration with additional
+file configuration for the Redoc UI. The configuration is applicable in any other `utoipa-redoc` setup as well.
+
+See the `build.rs` file that defines the Redoc config file and `redoc.json` where the [configuration options](https://redocly.com/docs/api-reference-docs/configuration/functionality/#configuration-options-for-api-docs)
+are defined. 
+
+For security restricted endpoints the super secret API key is: `utoipa-rocks`.
+
+Just run command below to run the demo application and browse to `http://localhost:8080/redoc`.
+
+```bash
+cargo run
+```
+
+If you want to see some logging, you may prepend the command with `RUST_LOG=debug` as shown below.
+
+```bash
+RUST_LOG=debug cargo run
+```
diff --git a/examples/todo-warp-redoc-with-file-config/build.rs b/examples/todo-warp-redoc-with-file-config/build.rs
@@ -0,0 +1,3 @@
+fn main() {
+    println!("cargo:rustc-env=UTOIPA_REDOC_CONFIG_FILE=redoc.json")
+}
diff --git a/examples/todo-warp-redoc-with-file-config/redoc.json b/examples/todo-warp-redoc-with-file-config/redoc.json
@@ -0,0 +1,3 @@
+{
+    "disableSearch": true
+}