Intro

So you’ve made your shiny new server with all these fancy Endpoints. Now comes the question, How do you tell someone what to access? You could write your own documentation, but that would take far too long, and you would be prone to making errors. A much better solution is to generate the docs from the code you’ve already written.

Such is the solution utoipa provides. It describes your endpoints in the OpenAPI standard in JSON, so it can be consumed by a suitable front-end. A front-end like SwaggerUI will display your endpoints so that it can consumed by a user with relative ease. We can bring SwaggerUI onto our server with the utoipa-swagger-ui crate, and it would look like this:

SwaggerUI with endpoints

SwaggerUI Making a HTTP Request to the described endpoint

Limitations

The only limitation we’ve come across is that swagger cannot send GET requests with a request body. You’ll have to use query parameters or change it to a POST method.

Actix Web Setup

We’ll being using actix_web but you could just as easily use axum, warp, tide or rocket. The entire project we setup here is available at this Github Repo. This is the structure we’ll be following:

 src
├──  auth.rs          # authentication extractors
├──  handler.rs       # endpoints go here
├──  main.rs          # server setup
├──  swagger_docs.rs  # swagger setup
└──  types.rs         # types w/ some swagger setup

We have the following endpoints setup:

• GET /v1/ - hello world example
• GET /v1/auth - authenticated hello world example
• POST /v1/create - basic post request which returns request
• DELETE /v1/delete/{email} - basic delete request which returns request

Utoipa Setup

we’ll be adding our 2 crates with actix integration features. Additionally we’ll also enable debug-embed in utoipa-swagger-ui so the docs endpoint is included in debug builds as well.

$ cargo add utoipa -F "actix_web"
$ cargo add utoipa-swagger-ui -F "actix_web debug-embed"

Next in the swagger_docs.rs file we’ll add the documentation struct ApiDoc. This struct will derive OpenAPI proc macro, which will be used to create our openapi.json file which will be used by swagger.