utoipa - Auto-generated OpenAPI documentation

Pronounced /u:ˈtoʊ:i.pɑ/ or /u:ˈtoʊˌaɪ.piˈeɪ/ whatever works better for you.

Want to have your API documented with OpenAPI? But don't want to be bothered with manual YAML or JSON tweaking? Would like it to be so easy that it would almost be utopic? Don't worry: utoipa is here to fill this gap. It aims to do, if not all, then most of the heavy lifting for you, enabling you to focus on writing the actual API logic instead of documentation. It aims to be minimal, simple and fast. It uses simple proc macros which you can use to annotate your code to have items documented.

The utoipa crate provides auto-generated OpenAPI documentation for Rust REST APIs. It treats code-first approach as a first class citizen and simplifies API documentation by providing simple macros for generating the documentation from your code.

It also contains Rust types of the OpenAPI spec, allowing you to write the OpenAPI spec only using Rust if auto generation is not your flavor or does not fit your purpose.

Long term goal of the library is to be the place to go when OpenAPI documentation is needed in any Rust codebase.

Utoipa is framework-agnostic, and could be used together with any web framework, or even without one. While being portable and standalone, one of its key aspects is simple integration with web frameworks.

Choose your flavor and document your API with ice-cold IPA

|Flavor|Support| |--|--| |actix-web|Parse path, path parameters and query parameters, recognize request body and response body, utoipa-actix-web bindings. See more at docs| |axum|Parse path and query parameters, recognize request body and response body, utoipa-axum bindings. See more at docs| |rocket| Parse path, path parameters and query parameters, recognize request body and response body. See more at docs| |Others*| Plain utoipa without extra flavor. This gives you all the basic benefits listed below in Features section but with little less automation.|

Others* = For example warp but could be anything.

Refer to the existing examples to find out more.

Features

• OpenAPI 3.1
• Pluggable, easy setup and integration with frameworks.
• No bloat, enable what you need.
• Support for generic types
  • Note!<br> Tuples, arrays and slices cannot be used as generic arguments on types. Types implementing ToSchema manually should not have generic arguments, as they are not composeable and will result compile error.
• Automatic schema collection from usages recursively.
  • Request body from either handler function arguments (if supported by framework) or from request_body attribute.
  • Response body from response body attribute or response content attribute.
• Various OpenAPI visualization tools supported out of the box.
• Rust type aliases via utoipa-config.

What's up with the word play?

The name comes from the words utopic and api where uto are the first three letters of utopic and the ipa is api reversed. Aaand... ipa is also an awesome type of beer :beer:.

Crate Features

• macros Enable utoipa-gen macros. This is enabled by default.
• yaml: Enables serde_norway serialization of OpenAPI objects.
• actix_extras: Enhances actix-web integration with being able to parse path, path and query parameters from actix web path attribute macros. See docs or examples for more details.
• rocket_extras: Enhances rocket framework integration with being able to parse path, path and query parameters from rocket path attribute macros. See docs or examples for more details.
• axum_extras: Enhances axum framework integration allowing users to use IntoParams without defining the parameter_in attribute. See docs or examples for more details.
• debug: Add extra traits such as debug traits to openapi definitions and elsewhere.
• chrono: Add support for chrono DateTime, Date, NaiveDate, NaiveDateTime, NaiveTime and Duration types. By default these types are parsed to string types with additional format information. format: date-time for DateTime and NaiveDateTime and format: date for Date and NaiveDate according RFC3339 as ISO-8601. To override default string representation users have to use value_type attribute to override the type. See docs for more details.
• time: Add support for time OffsetDateTime, PrimitiveDateTime, Date, and Duration types. By default these types are parsed as string. OffsetDateTime and PrimitiveDateTime will use date-time format. Date will use date format and Duration will not have any format. To override default string representation users have to use value_type attribute to override the type. See docs for more details.
• jiff_0_2 Add support for jiff 0.2 Timestamp, Zoned, and civil::Date types. By default these types are parsed as string. Timestamp and Zoned will use date-time format. civil::Date will use date format. To override default string representation users have to use value_type attribute to override the type. See docs for more details.
• decimal: Add support for rust_decimal Decimal type. By default it is interpreted as String. If you wish to change the format you need to override the type. See the value_type in component derive docs.
• decimal_float: Add support for rust_decimal Decimal type. By default it is interpreted as Number. This feature is mutually exclusive with decimal and allow to change the default type used in your documentation for Decimal much like serde_with_float feature exposed by rust_decimal.
• uuid: Add support for uuid. Uuid type will be presented as String with format uuid in OpenAPI spec.
• ulid: Add support for ulid. Ulid type will be presented as String with format ulid in OpenAPI spec.
• url: Add support for url. Url type will be presented as String with format uri in OpenAPI spec.
• smallvec: Add support for smallvec. SmallVec will be treated as Vec.
• openapi_extensions: Adds traits and functions that provide extra convenience functions. See the request_body docs for an example.
• repr: Add support for repr_serde's repr(u*) and repr(i*) attributes to unit type enums for C-like enum representation. See docs for more details.
• preserve_order: Preserve order of properties when serializing the schema for a component. When enabled, the properties are listed in order of fields in the corresponding struct definition. When disabled, the properti