docs: open api docs utoipa by taddes · Pull Request #2023 · mozilla-services/syncstorage-rs

taddes · 2026-01-26T19:39:29Z

Description

OpenAPI docs would be useful to collect and publish to clarify our API.

The utopia crate w/ the actix_extras feature can parse our actix-web route definitions to produce OpenAPI docs, and its accompanying utoipa-swagger-ui crate can serve those docs via actix-web.

This PR imports utoipa and swagger to support the OpenAPI spec and annotates the web handlers for tokenserver and sync to introduce the API documentation. This requires special proc macros that are recognized by OpenAPI

For consistency and simplicity, I have added to the github actions to generate and publish the swagger docs as well. The documentation page also lays out ways to see the documentation locally using Docker and a few other methods. Just follow the instructions to test for yourself. There is also an example script that generates the openapi.json file that is required first.

Also resolves cargo-audit CVE related to time create

Issue(s)

Closes STOR-381.

chenba · 2026-01-28T22:32:48Z

+cargo run --example generate_openapi_spec > openapi.json
+```
+
+### Viewing the Spec Locally (Without Running the Server)


What do you think of the idea of creating a make target that can generate and preview the swagger docs?

Great idea, I'll add that 👍

chenba · 2026-01-29T02:30:39Z

 [workspace.package]
 version = "0.21.1"
 authors = [
-  "Ben Bangert <ben@groovie.org>",


That seems harsh.

I know, I too am sad Ben left Mozilla... His was the first name that came up so I updated it to Phil. What we really need is a mail group for the sync/storage team. I can put it back for posterity if you feel strongly.

I don't put too much importance in these author fields but if anything I'd rather add more to them than remove.

However we apparently have a sync-backend@mozilla.com that you made in 2024, so we could make that the sole authors if you want (and add Barry to this mailing list).

Thx, moved us to that and added Barry!

chenba · 2026-01-29T02:33:49Z

+    summary = "Get collection timestamps",
+    description = "Returns an object mapping collection names associated with the account to the last-modified time for each collection.",
+    params(
+        ("uid" = String, Path, description = "User ID")


Should we explain how the user can get this uid value? Presumably we want people to interact with the endpoints.

Folks would have to probably use the about:sync extension to get their uid

chenba · 2026-01-29T14:10:49Z


+#[utoipa::path(
+    get,
+    path = "/1.0/{application}/{version}",


I think application and version should be params below?

chenba · 2026-01-29T14:31:54Z

+        (status = 401, description = "Unauthorized - Invalid authentication"),
+        (status = 503, description = "Service unavailable - No nodes available"),
+    )
+)]


There is nothing here about authorization. And the UI doesn't offer a way to pass anything in through headers.

Yeah, I'll have to dig a little deeper on how to deal with this for the configuration for the live preview mode.

I'd be fine merging this pretty much as is, we can log a separate issue for supporting Auth headers

Sounds good @pjenvey , can file an additional ticket as I explore that a bit and we see how it looks when deployed.

chenba · 2026-01-29T14:35:16Z

+        (status = 200, description = "Collection timestamps retrieved successfully", content_type = "application/json"),
+        (status = 401, description = "Unauthorized"),
+    )
+)]


There is no way to authorize these syncserver requests. The only param I can enter on the UI is the uid but that isn't enough.

chenba · 2026-01-29T14:41:04Z

+    summary = "Get sync token",
+    description = "Allocates a sync storage node and returns authentication credentials for accessing it. This is the main Tokenserver endpoint used by Firefox Sync clients.",
+    responses(
+        (status = 200, description = "Token generated successfully", body = TokenserverResult, content_type = "application/json"),


Without making a successful request, readers wouldn't know the shape of TokenserverResult. It would be nice if there's a response schema.

With the 200 response, there is actually a TokenserverResult that can be seen, whether the request is successful or not. Really glad you mentioned this though, because I hadn't added the Tokenserver stage & prod references to the Api doc config and also made sure to add to the documentation.

chenba · 2026-01-29T14:49:56Z

+        ("uid" = String, Path, description = "User ID"),
+        ("collection" = String, Path, description = "Collection name"),
+        ("ids" = Option<String>, Query, description = "Comma-separated list of BSO IDs to return (max 100)"),
+        ("newer" = Option<f64>, Query, description = "Return only items with modified time strictly greater than this timestamp"),


Might be good to mention the resolution of the timestamps.

pjenvey · 2026-01-29T22:54:41Z

+        description = "OpenAPI documentation for Syncstorage and Tokenserver endpoints."
+    ),
+    servers(
+        (url = "https://sync-1-us-west1-g.sync.services.mozilla.com", description = "US West Production"),


Suggested change

(url = "https://sync-1-us-west1-g.sync.services.mozilla.com", description = "US West Production"),

(url = "https://sync-us-west1-g.sync.services.allizom.org", description = "US West Stage"),

(url = "https://sync-1-us-west1-g.sync.services.mozilla.com", description = "US West Production"),

(if anyone wants to play around with test traffic, maybe encourage stage)

Good call with stage, can add a suggestion in docs.

pjenvey · 2026-01-30T19:10:28Z

+   ```
+   Then open http://localhost:8080
+
+2. **Generate the spec on a compatible machine** (or use CI):


This seems a little confusing with 1) mentioning this command but really 1/3/4 all need it (should 2 be removed and 1)'s mention of the command moved ahead of all these sections?)

Sure, that makes sense.

taddes · 2026-01-30T23:13:54Z

Note: once we finally cut a new release with this feature, we may go back and make some adjustments to the URL we point to and see if the generated swagger docs (which eventually end up as part of the compiled and deployed Syncstorage) are more feature-rich than the current state.

chenba · 2026-02-02T15:18:16Z

+OPENAPI_FILE := openapi.json
+
+.PHONY: api-prev
+api-prev: ## Generate live preview of OpenAPI Swagger Docs and open in browser (port 8080).


I tried this and the server stops as soon as it's started.

Is your Docker daemon/Docker desktop running? Works fine for me.

docker container ls showed the expected output so it appears to be running.

chenba · 2026-02-02T15:34:21Z

Thanks @taddes for this work.

I think I need to understand the goal of this effort better. If it is to allow people to interact with the API endpoints, then it is not quite there. The UI for the very first step of exchanging an FxA OAuth access token for a Sync auth token does not have a way for the user to input the access token. (Presuming the user know how to grab an FxA access token that's authorized to access Sync.)

If we only want to list the API endpoints, then let's remove the interactivity. We still should list the header(s) for the endpoints, however.

taddes · 2026-02-02T15:57:07Z

Thanks @taddes for this work.

I think I need to understand the goal of this effort better. If it is to allow people to interact with the API endpoints, then it is not quite there. The UI for the very first step of exchanging an FxA OAuth access token for a Sync auth token does not have a way for the user to input the access token. (Presuming the user know how to grab an FxA access token that's authorized to access Sync.)

If we only want to list the API endpoints, then let's remove the interactivity. We still should list the header(s) for the endpoints, however.

This was a very old ticket to basically just add the OpenAPI support. There isn't an explicit necessary goal of it being interactive, though that's a nice plus. I had mentioned before that the auth parts of this may make it tricky, and we're not going to know more until we actually cut a new version of Sync with this feature that exposes the API as part of the compiled Sync. We can file an additional ticket to expand that as needed. It might in the end be a bridge too far to have it fully interactive. However, the endpoints still have response codes and the shapes of some of the returned data.

pjenvey · 2026-02-04T19:42:40Z

 validator = "0.20"
 validator_derive = "0.20"
 woothee = "0.13"
+utoipa = "5.4.0"


let's move this into the root Cargo.toml w/ tokenserver-common also using it

pjenvey · 2026-02-04T19:43:41Z

+        (status = 401, description = "Unauthorized - Invalid authentication"),
+        (status = 503, description = "Service unavailable - No nodes available"),
+    )
+)]


I'd be fine merging this pretty much as is, we can log a separate issue for supporting Auth headers

taddes · 2026-02-06T21:24:55Z

Also resolves cargo-audit CVE related to time create:

Version:   0.3.41
Title:     Denial of Service via Stack Exhaustion
Date:      2026-02-05
ID:        RUSTSEC-2026-0009
URL:       https://rustsec.org/advisories/RUSTSEC-2026-0009
Severity:  6.8 (medium)
Solution:  Upgrade to >=0.3.47
Dependency tree:
time 0.3.41
├── syncstorage-settings 0.21.1
│   ├── syncstorage-spanner 0.21.1
│   │   └── syncstorage-db 0.21.1
│   │       └── syncserver 0.21.1
│   ├── syncstorage-postgres 0.21.1
│   │   └── syncstorage-db 0.21.1
│   ├── syncstorage-mysql 0.21.1
│   │   └── syncstorage-db 0.21.1
│   ├── syncstorage-db 0.21.1
│   ├── syncserver-settings 0.21.1
│   │   ├── tokenserver-db 0.21.1
│   │   │   └── syncserver 0.21.1
│   │   ├── syncstorage-mysql 0.21.1
│   │   ├── syncstorage-db 0.21.1
│   │   └── syncserver 0.21.1
│   └── syncserver 0.21.1
├── syncserver 0.21.1
├── slog-term 2.9.2
│   ├── syncserver 0.21.1
│   └── slog-envlogger 2.2.0
│       └── syncserver 0.21.1
├── sentry-types 0.42.0
│   └── sentry-core 0.42.0
│       ├── sentry-tracing 0.42.0
│       │   └── sentry 0.42.0
│       │       ├── syncserver-common 0.21.1
│       │       │   ├── tokenserver-postgres 0.21.1
│       │       │   │   └── tokenserver-db 0.21.1
│       │       │   ├── tokenserver-mysql 0.21.1
│       │       │   │   └── tokenserver-db 0.21.1
│       │       │   ├── tokenserver-db-common 0.21.1
│       │       │   │   ├── tokenserver-postgres 0.21.1
│       │       │   │   ├── tokenserver-mysql 0.21.1
│       │       │   │   └── tokenserver-db 0.21.1
│       │       │   ├── tokenserver-db 0.21.1
│       │       │   ├── tokenserver-common 0.21.1
│       │       │   │   ├── tokenserver-settings 0.21.1
│       │       │   │   │   ├── tokenserver-postgres 0.21.1
│       │       │   │   │   ├── tokenserver-mysql 0.21.1
│       │       │   │   │   ├── tokenserver-db 0.21.1
│       │       │   │   │   ├── tokenserver-auth 0.21.1
│       │       │   │   │   │   └── syncserver 0.21.1
│       │       │   │   │   ├── syncserver-settings 0.21.1
│       │       │   │   │   └── syncserver 0.21.1
│       │       │   │   ├── tokenserver-postgres 0.21.1
│       │       │   │   ├── tokenserver-mysql 0.21.1
│       │       │   │   ├── tokenserver-db-common 0.21.1
│       │       │   │   ├── tokenserver-auth 0.21.1
│       │       │   │   └── syncserver 0.21.1
│       │       │   ├── tokenserver-auth 0.21.1
│       │       │   ├── syncstorage-spanner 0.21.1
│       │       │   ├── syncstorage-settings 0.21.1
│       │       │   ├── syncstorage-postgres 0.21.1
│       │       │   ├── syncstorage-mysql 0.21.1
│       │       │   ├── syncstorage-db-common 0.21.1
│       │       │   │   ├── syncstorage-spanner 0.21.1
│       │       │   │   ├── syncstorage-postgres 0.21.1
│       │       │   │   ├── syncstorage-mysql 0.21.1
│       │       │   │   └── syncstorage-db 0.21.1
│       │       │   ├── syncstorage-db 0.21.1
│       │       │   ├── syncserver-settings 0.21.1
│       │       │   ├── syncserver-db-common 0.21.1
│       │       │   │   ├── tokenserver-postgres 0.21.1
│       │       │   │   ├── tokenserver-mysql 0.21.1
│       │       │   │   ├── tokenserver-db-common 0.21.1
│       │       │   │   ├── tokenserver-db 0.21.1
│       │       │   │   ├── syncstorage-spanner 0.21.1
│       │       │   │   ├── syncstorage-postgres 0.21.1
│       │       │   │   ├── syncstorage-mysql 0.21.1
│       │       │   │   ├── syncstorage-db-common 0.21.1
│       │       │   │   ├── syncstorage-db 0.21.1
│       │       │   │   └── syncserver 0.21.1
│       │       │   └── syncserver 0.21.1
│       │       └── syncserver 0.21.1
│       ├── sentry-debug-images 0.42.0
│       │   └── sentry 0.42.0
│       ├── sentry-contexts 0.42.0
│       │   └── sentry 0.42.0
│       ├── sentry-backtrace 0.42.0
│       │   ├── syncserver-common 0.21.1
│       │   ├── sentry-tracing 0.42.0
│       │   └── sentry 0.42.0
│       └── sentry 0.42.0
├── plist 1.7.4
│   └── os_info 3.12.0
│       └── sentry-contexts 0.42.0
└── actix-web 4.11.0
    ├── utoipa-swagger-ui 9.0.2
    │   └── syncserver 0.21.1
    ├── tokenserver-common 0.21.1
    ├── syncstorage-spanner 0.21.1
    ├── syncserver-common 0.21.1
    ├── syncserver 0.21.1
    └── actix-cors 0.7.1
        └── syncserver 0.21.1

taddes self-assigned this Jan 26, 2026

taddes force-pushed the docs/open-api-docs-utoipa-STOR-381 branch from 4d40a9b to 98b3ece Compare January 28, 2026 19:24

taddes changed the title ~~WIP: docs: open api docs utoipa~~ docs: open api docs utoipa Jan 28, 2026

taddes marked this pull request as ready for review January 28, 2026 19:28

taddes had a problem deploying to github-pages January 28, 2026 19:31 — with GitHub Actions Failure

taddes had a problem deploying to github-pages January 28, 2026 20:05 — with GitHub Actions Failure

taddes had a problem deploying to github-pages January 28, 2026 20:11 — with GitHub Actions Failure

taddes had a problem deploying to github-pages January 28, 2026 20:16 — with GitHub Actions Failure

chenba reviewed Jan 28, 2026

View reviewed changes

taddes requested a review from pjenvey January 28, 2026 22:49

chenba reviewed Jan 29, 2026

View reviewed changes

taddes force-pushed the docs/open-api-docs-utoipa-STOR-381 branch from f925335 to 91adafd Compare January 29, 2026 18:47

pjenvey reviewed Jan 30, 2026

View reviewed changes

taddes force-pushed the docs/open-api-docs-utoipa-STOR-381 branch from 4e53172 to ed6d5f9 Compare January 30, 2026 22:30

taddes requested review from chenba and pjenvey January 30, 2026 23:05

chenba reviewed Feb 2, 2026

View reviewed changes

taddes force-pushed the docs/open-api-docs-utoipa-STOR-381 branch from bdafc7e to ac9e11f Compare February 2, 2026 19:58

pjenvey reviewed Feb 4, 2026

View reviewed changes

taddes force-pushed the docs/open-api-docs-utoipa-STOR-381 branch from ac9e11f to ff7837f Compare February 5, 2026 03:28

taddes requested a review from pjenvey February 5, 2026 03:28

taddes force-pushed the docs/open-api-docs-utoipa-STOR-381 branch from ff7837f to 5045c96 Compare February 6, 2026 20:33

taddes added 3 commits February 6, 2026 15:33

utoipa and swagger basic config and boilerplate

2f98ebd

tokenserver handlers

cea018f

openapi spec annotations and handler api definitions

5ec9332

taddes added 15 commits February 6, 2026 15:33

example gen for openapi.json

f4154ee

update workflow to publish swagger

670ef89

documentation updates and openapi docs

e14fc0b

publish docs action update

9e05ccc

test

c3dd3ab

test

37a66e3

tokenserver params and error responses

beb8c94

change name to match

8cd3a19

doc updates

9fb8406

Makefile for live api example

6ed08f3

timestamp resolution

6ebcc2c

update to team distro email

77f8764

update docs for clarity and add envs

901a657

tokenserver url and doc refs

8e94e2c

cargo.toml updates

5045c96

pjenvey previously approved these changes Feb 6, 2026

View reviewed changes

taddes dismissed pjenvey’s stale review via f24fb1d February 6, 2026 21:11

cargo audit

f24fb1d

taddes requested a review from pjenvey February 6, 2026 21:23

pjenvey approved these changes Feb 6, 2026

View reviewed changes

taddes merged commit 62bd7d2 into master Feb 6, 2026
32 checks passed

taddes deleted the docs/open-api-docs-utoipa-STOR-381 branch February 6, 2026 22:05

	(url = "https://sync-1-us-west1-g.sync.services.mozilla.com", description = "US West Production"),
	(url = "https://sync-us-west1-g.sync.services.allizom.org", description = "US West Stage"),
	(url = "https://sync-1-us-west1-g.sync.services.mozilla.com", description = "US West Production"),

Conversation

taddes commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue(s)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

taddes Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pjenvey Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

taddes commented Jan 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chenba commented Feb 2, 2026

Uh oh!

taddes commented Feb 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

taddes commented Feb 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

taddes commented Jan 26, 2026 •

edited

Loading

taddes Jan 29, 2026 •

edited

Loading

pjenvey Jan 29, 2026 •

edited

Loading