From c2e675b12e05a1e0ff8280caec5d758ee7265ae6 Mon Sep 17 00:00:00 2001 From: Spencer Ferris <3319370+spencewenski@users.noreply.github.com> Date: Sun, 13 Oct 2024 21:12:50 -0700 Subject: [PATCH] docs: Add comparison to Axum (#424) --- book/src/SUMMARY.md | 12 +++++++++--- book/src/ch-00-introduction.md | 4 ++-- book/src/ch-01-00-comparisons.md | 8 ++++++++ book/src/ch-01-01-comparisons-axum.md | 15 +++++++++++++++ book/src/ch-01-comparisons.md | 1 - ...ing-started.md => ch-02-00-getting-started.md} | 0 .../{ch-03-features.md => ch-03-00-features.md} | 0 book/src/ch-03-01-features-http.md | 1 + book/src/ch-03-02-features-middleware.md | 1 + book/src/ch-03-03-features-app-state.md | 1 + book/src/ch-03-04-features-openapi.md | 1 + book/src/ch-03-05-features-tracing.md | 1 + 12 files changed, 39 insertions(+), 6 deletions(-) create mode 100644 book/src/ch-01-00-comparisons.md create mode 100644 book/src/ch-01-01-comparisons-axum.md delete mode 100644 book/src/ch-01-comparisons.md rename book/src/{ch-02-getting-started.md => ch-02-00-getting-started.md} (100%) rename book/src/{ch-03-features.md => ch-03-00-features.md} (100%) create mode 100644 book/src/ch-03-01-features-http.md create mode 100644 book/src/ch-03-02-features-middleware.md create mode 100644 book/src/ch-03-03-features-app-state.md create mode 100644 book/src/ch-03-04-features-openapi.md create mode 100644 book/src/ch-03-05-features-tracing.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index eaa1fd73..8c1c2da5 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -2,6 +2,12 @@ [Introduction](ch-00-introduction.md) -- [Web framework comparisons](ch-01-comparisons.md) -- [Getting started](ch-02-getting-started.md) -- [Roadster features](ch-03-features.md) +- [Web framework comparisons](ch-01-00-comparisons.md) + - [Roadster vs. Axum](ch-01-01-comparisons-axum.md) +- [Getting started](ch-02-00-getting-started.md) +- [Roadster features](ch-03-00-features.md) + - [HTTP Service with Axum](ch-03-01-features-http.md) + - [Axum middleware](ch-03-02-features-middleware.md) + - [OpenAPI with Aide](ch-03-04-features-openapi.md) + - [Tracing](ch-03-05-features-tracing.md) + - [Axum state](ch-03-03-features-app-state.md) diff --git a/book/src/ch-00-introduction.md b/book/src/ch-00-introduction.md index 50c20322..92e69a1e 100644 --- a/book/src/ch-00-introduction.md +++ b/book/src/ch-00-introduction.md @@ -13,8 +13,8 @@ customizable, and pluggable. This allows you to focus on creating your applicati dependencies, while still allowing you the flexibility to customize your dependencies if needed. If you're unsure if Roadster is the best fit for your project, a collection of comparisons to other Rust web frameworks -can be found in [Web framework comparisons](ch-01-comparisons.md). The full list of Roadster's features can be -found in [Roadster features](ch-03-features.md). +can be found in [Web framework comparisons](ch-01-00-comparisons.md). The full list of Roadster's features can be +found in [Roadster features](ch-03-00-features.md). ## Prerequisite reading diff --git a/book/src/ch-01-00-comparisons.md b/book/src/ch-01-00-comparisons.md new file mode 100644 index 00000000..64b14517 --- /dev/null +++ b/book/src/ch-01-00-comparisons.md @@ -0,0 +1,8 @@ +# Web framework comparisons + +This chapter compares [Roadster](https://crates.io/crates/roadster) to other Rust web frameworks to help you determine +if Roadster is the best fit for your project. + +If you're considering Roadster, we assume you have already decided that Rust is the best fit for your project. +Therefore, we do not provide comparisons to non-Rust web frameworks, such +as [Rails](https://rubyonrails.org/), [Django](https://www.djangoproject.com/), or [Laravel](https://laravel.com/). diff --git a/book/src/ch-01-01-comparisons-axum.md b/book/src/ch-01-01-comparisons-axum.md new file mode 100644 index 00000000..44e9ffbc --- /dev/null +++ b/book/src/ch-01-01-comparisons-axum.md @@ -0,0 +1,15 @@ +# Roadster vs. Axum + +Roadster actually uses [Axum](https://crates.io/crates/axum) to provide an HTTP server, so anything you can do with +plain Axum you can do with Roadster. However, using Roadster has some benefits compared to configuring Axum yourself: + +- Roadster registers a collection of common middleware with sensible default configurations. + See [Axum middleware](ch-03-02-features-middleware.md) for more information. +- Roadster creates an `AppContext` to use as the Axum State that contains all the dependency objects created by + Roadster, such as the DB connection, app config, etc. See [Axum state](ch-03-03-features-app-state.md) for more + information. +- Roadster auto-generates a unique request ID for each request, if one wasn't provided in the request +- Roadster configures [Tracing](https://crates.io/crates/tracing) and enables instrumentation for requests. + See [Tracing](ch-03-05-features-tracing.md) for more information. +- Roadster supports registering API routes using [Aide](https://crates.io/crates/aide) to enable auto-generating an + OpenAPI schema and playground. See [OpenAPI with Aide](ch-03-04-features-openapi.md) for more information. diff --git a/book/src/ch-01-comparisons.md b/book/src/ch-01-comparisons.md deleted file mode 100644 index 24ef9996..00000000 --- a/book/src/ch-01-comparisons.md +++ /dev/null @@ -1 +0,0 @@ -# Web framework comparisons diff --git a/book/src/ch-02-getting-started.md b/book/src/ch-02-00-getting-started.md similarity index 100% rename from book/src/ch-02-getting-started.md rename to book/src/ch-02-00-getting-started.md diff --git a/book/src/ch-03-features.md b/book/src/ch-03-00-features.md similarity index 100% rename from book/src/ch-03-features.md rename to book/src/ch-03-00-features.md diff --git a/book/src/ch-03-01-features-http.md b/book/src/ch-03-01-features-http.md new file mode 100644 index 00000000..be8bf08d --- /dev/null +++ b/book/src/ch-03-01-features-http.md @@ -0,0 +1 @@ +# HTTP Service with Axum \ No newline at end of file diff --git a/book/src/ch-03-02-features-middleware.md b/book/src/ch-03-02-features-middleware.md new file mode 100644 index 00000000..5664e74e --- /dev/null +++ b/book/src/ch-03-02-features-middleware.md @@ -0,0 +1 @@ +# Axum middleware diff --git a/book/src/ch-03-03-features-app-state.md b/book/src/ch-03-03-features-app-state.md new file mode 100644 index 00000000..48f56d5e --- /dev/null +++ b/book/src/ch-03-03-features-app-state.md @@ -0,0 +1 @@ +# Axum state diff --git a/book/src/ch-03-04-features-openapi.md b/book/src/ch-03-04-features-openapi.md new file mode 100644 index 00000000..06987374 --- /dev/null +++ b/book/src/ch-03-04-features-openapi.md @@ -0,0 +1 @@ +# OpenAPI with Aide diff --git a/book/src/ch-03-05-features-tracing.md b/book/src/ch-03-05-features-tracing.md new file mode 100644 index 00000000..6c328cf4 --- /dev/null +++ b/book/src/ch-03-05-features-tracing.md @@ -0,0 +1 @@ +# Tracing