Skip to content

Commit

Permalink
Add redoc support for utoipa. (#720)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
juhaku authored Aug 6, 2023
1 parent a9f4797 commit 6baa9b0
Show file tree
Hide file tree
Showing 29 changed files with 1,085 additions and 17 deletions.
3 changes: 3 additions & 0 deletions .github/workflows/build.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ jobs:
- utoipa
- utoipa-gen
- utoipa-swagger-ui
- utoipa-redoc
fail-fast: true
runs-on: ubuntu-latest

Expand Down Expand Up @@ -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"
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/draft.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ jobs:
- utoipa
- utoipa-gen
- utoipa-swagger-ui
- utoipa-redoc
runs-on: ubuntu-latest

steps:
Expand Down
8 changes: 2 additions & 6 deletions Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"]
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 4 additions & 1 deletion examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
7 changes: 3 additions & 4 deletions examples/rocket-todo/Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
4 changes: 3 additions & 1 deletion examples/rocket-todo/README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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
```
Expand Down
2 changes: 2 additions & 0 deletions examples/rocket-todo/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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![
Expand Down
3 changes: 2 additions & 1 deletion examples/todo-actix/Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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]
4 changes: 3 additions & 1 deletion examples/todo-actix/README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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
```
Expand Down
2 changes: 2 additions & 0 deletions examples/todo-actix/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand Down Expand Up @@ -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()),
)
Expand Down
3 changes: 2 additions & 1 deletion examples/todo-axum/Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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"
Expand Down
4 changes: 3 additions & 1 deletion examples/todo-axum/README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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
```
Expand Down
2 changes: 2 additions & 0 deletions examples/todo-axum/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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),
Expand Down
22 changes: 22 additions & 0 deletions examples/todo-warp-redoc-with-file-config/Cargo.toml
Original file line number Diff line number Diff line change
@@ -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]
27 changes: 27 additions & 0 deletions examples/todo-warp-redoc-with-file-config/README.md
Original file line number Diff line number Diff line change
@@ -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
```
3 changes: 3 additions & 0 deletions examples/todo-warp-redoc-with-file-config/build.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
fn main() {
println!("cargo:rustc-env=UTOIPA_REDOC_CONFIG_FILE=redoc.json")
}
3 changes: 3 additions & 0 deletions examples/todo-warp-redoc-with-file-config/redoc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"disableSearch": true
}
Loading

0 comments on commit 6baa9b0

Please sign in to comment.