# ADR: Expose API documentation route using Redoc (instead of Swagger UI)

- Date: **2024-04-25**
- Author: **Rémi Bardon <[remi@remibardon.name](mailto:remi@remibardon.name)>**
<!-- Proposed|Accepted|Rejected, with date and channel if applicable -->
- Status: **Accepted** via [#13](https://github.com/prose-im/prose-pod-api/pull/13) (2024-04-28)
<!-- "ø" or a nested unordered list linking to other ADRs and their date -->
- Relates to:
  - [Describe Prose Pod API using the OpenAPI Specification](./2023-12-18-a-describe-with-openapi.md) (2023-12-18)
  - [Write the OpenAPI description file manually](./2024-04-25-a-write-openapi-manually.md) (2024-04-25)
<!-- "ø" or a nested unordered list linking to other ADRs and their date -->
- Superseded by:
  - [Stop exposing the OpenAPI docs](./2025-09-13-a-stop-exposing-openapi-docs.md) (2025-09-13)
<!-- "No" or "Yes" with the deprecation date -->
- Deprecated: Yes (2025-09-13)

## Context

<!--
This section describes the forces at play, including technological, political,
social, and project local. These forces are probably in tension, and should be
called out as such. The language in this section is value-neutral. It is simply
describing facts.
-->

At the time of writing this ADR, we are using [`utoipa-swagger-ui`] to easily
expose a [Swagger UI] route from the data structure generated by [`utoipa`].
As explained in [Write the OpenAPI description file manually](./2024-04-25-a-write-openapi-manually.md),
we will get rid of `utoipa` and write the OpenAPI specification file ourselves.
Since [`utoipa-swagger-ui`] won't work anymore, we will have to reimplement an
graphical API documentation route.

[Swagger UI] is ok on desktop, but it's not responsive and has a lot of bad
UI and UX design. Today might be a good occasion to switch to a new graphical
documentation tool.

[Redoc] seems like a good fit: it's lighweight, renders well and looks like
modern documentations (see the [GitHub REST API documentation]).
It supports [multiple deployment options][redoc-deployment-options],
and more importantly self-hosting.

It could be interesting to use the tool used by GitHub to generate their
[REST API documentation][GitHub REST API documentation] but it doesn't seem
to be usable as a standalone tool.

## Decision

<!--
This section describes our response to these forces. It is stated in full
sentences, with active voice. "We will …"
-->

We will get rid of the [Swagger UI] route (and therefore [`utoipa-swagger-ui`])
and use [Redoc] instead. There is no Rust crate providing native Rust support
for Redoc (apart from [`utoipa-redoc`] which we can't use) so we will expose a
raw HTML route (see [Use Redoc in HTML]).

To avoid cross-origin request, we will [self-host the dependencies] and get rid
of the call to `fonts.googleapis.com`.

## Consequences

<!--
This section describes the resulting context, after applying the decision.
All consequences should be listed here, not just the "positive" ones.
A particular decision may have positive, negative, and neutral consequences,
but all of them affect the team and project in the future.
-->

Switching from [Swagger UI] to [Redoc], the graphical API documentation page
will now be responsive and better in terms of UI and UX. However, we will loose
Swagger UI's "Run" feature which allowed one to run a request directly from the
documentation page. This is a minor loss compared to what we will gain from the
change.

Since we won't be able to use the plug-and-play [`utoipa-redoc`], we will have
a little setup work to do to reimplement the graphical documentation route.
However, using [Rocket's `Template`s] should make this task very easy.

[GitHub REST API documentation]: https://docs.github.com/en/rest/orgs/orgs "REST API endpoints for organizations"
[Redoc]: https://redocly.com/redoc/ "Redoc homepage"
[redoc-deployment-options]: https://redocly.com/docs/redoc/deployment/intro/ "Redoc deployment guide"
[Rocket's `Template`s]: https://rocket.rs/guide/v0.5/responses/#templates "Responses > Templates - Rocket Web Framework"
[self-host the dependencies]: https://redocly.com/docs/redoc/deployment/html/#self-host-dependencies "Use the Redoc HTML element"
[Swagger UI]: https://swagger.io/tools/swagger-ui/ "REST API Documentation Tool | Swagger UI"
[Use Redoc in HTML]: https://redocly.com/docs/redoc/deployment/html "Use the Redoc HTML element"
[`utoipa`]: https://crates.io/crates/utoipa "utoipa - crates.io"
[`utoipa-redoc`]: https://crates.io/crates/utoipa-redoc "utoipa-redoc - crates.io"
[`utoipa-swagger-ui`]: https://crates.io/crates/utoipa-swagger-ui "utoipa-swagger-ui - crates.io"
