utoipa - Auto-generated OpenAPI documentation

• repr: Add support for reprserde's repr(u) and repr(i) attributes to unit type enums for

• preserve_order: Preserve order of properties when serializing the schema for a component.

• preservepathorder: Preserve order of OpenAPI Paths according to order they have been

• indexmap: Add support for indexmap. When enabled IndexMap will be rendered as a map similar to

• nonstrictintegers: Add support for non-standard integer formats int8, int16, uint8, uint16, uint32, and uint64.
• rc_schema: Add ToSchema support for Arc<T> and Rc<T> types. Note! serde rc feature flag must be enabled separately to allow

• config Enables utoipa-config for the project which allows defining global configuration options for utoipa.

Default Library Support

• Implicit partial support for serde attributes. See docs for more details.
• Support for http StatusCode in responses.

Install

Add dependency declaration to Cargo.toml.

[dependencies]
utoipa = "5"

Examples

Create type with ToSchema and use it in #[utoipa::path(...)] that is registered to the OpenApi.

use utoipa::{OpenApi, ToSchema};
#[derive(ToSchema)] struct Pet {    id: u64,    name: String,    age: Option<i32>, }
mod pet_api {     /// Get pet by id     ///     /// Get pet from database by pet id     #[utoipa::path(         get,         path = "/pets/{id}",         responses(             (status = 200, description = "Pet found successfully", body = Pet),             (status = NOT_FOUND, description = "Pet was not found")         ),         params(             ("id" = u64, Path, description = "Pet database id to get Pet for"),         )     )]     async fn getpetbyid(petid: u64) -> Result<Pet, NotFound> {         Ok(Pet {             id: pet_id,             age: None,             name: "lightning".to_string(),         })     } }
#[derive(OpenApi)] #[openapi(paths(petapi::getpetbyid))] struct ApiDoc;
println!("{}", ApiDoc::openapi().toprettyjson().unwrap());

{
  "openapi": "3.1.0",
  "info": {
    "title": "application name from Cargo.toml",
    "description": "description from Cargo.toml",
    "contact": {
      "name": "author name from Cargo.toml",
      "email": "author email from Cargo.toml"
    },
    "license": {
      "name": "license from Cargo.toml"
    },
    "version": "version from Cargo.toml"
  },
  "paths": {
    "/pets/{id}": {
      "get": {
        "tags": [
          "pet_api"
        ],
        "summary": "Get pet by id",
        "description": "Get pet from database by pet id",
        "operationId": "getpetby_id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Pet database id to get Pet for",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pet found successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          },
          "404": {
            "description": "Pet was not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "age": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32"
          },
          "id": {
            "type": "integer",
            "format": "int64",
            "minimum": 0
          },
          "name": {
            "type": "string"
          }
        }
      }
    }
  }
}

Modify OpenAPI at runtime

You can modify generated OpenAPI at runtime either via generated types directly or using Modify trait.

Modify generated OpenAPI via types directly.

#[derive(OpenApi)]
#[openapi(
    info(description = "My Api description"),
)]
struct ApiDoc;
let mut doc = ApiDoc::openapi(); doc.info.title = String::from("My Api");

You can even convert the generated OpenApi to OpenApiBuilder.

let builder: OpenApiBuilder = ApiDoc::openapi().into();

See Modify trait for examples on how to modify generated OpenAPI via it.

Go beyond the surface

• See how to serve OpenAPI doc via Swagger UI check utoipa-swagger-ui crate for more details.
• Browse to examples for more comprehensive examples.
• Check IntoResponses and ToResponse for examples on deriving responses.
• More about OpenAPI security in security documentation.
• Dump generated API doc to file at build time. See issue 214 comment.

FAQ

How to implement ToSchema for external type?

There are few ways around this that are elaborated here in detail.

Auto discover for OpenAPI schemas and paths?

Currently there is no build in solution to automatically discover the OpenAPI types but for your luck there is a pretty neat crate that just does this for you called utoipauto.

License

Licensed under either of Apache 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, shall be dual licensed, without any additional terms or conditions.