OpenAPI

Modified from utoipaopen in new window, It uses simple proc macros which you can use to annotate your code to have items documented.

Crate Features

  • yaml Enables serde_yaml serialization of OpenAPI objects.
  • chrono Add support for chronoopen in new window DateTime, Date, NaiveDate and Duration types. By default these types are parsed to string types with additional format information. format: date-time for DateTime and format: date for Date and NaiveDate according RFC3339open in new window as ISO-8601. To override default string representation users have to use value_type attribute to override the type. See docsopen in new window for more details.
  • time Add support for timeopen in new window 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 docsopen in new window for more details.
  • decimal Add support for rust_decimalopen in new window 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 [ToSchema derive docs][as_schema_derive].
  • uuid Add support for uuidopen in new window. Uuid type will be presented as String with format uuid in OpenAPI spec.
  • smallvec Add support for smallvecopen in new window. SmallVec will be treated as Vec.
  • indexmap Add support for indexmapopen in new window. When enabled IndexMap will be rendered as a map similar to BTreeMap and HashMap.

Endpoint

Endpoint attribute macro implements OpenAPI path for the decorated function.

Macro accepts set of attributes that can be used to configure and override default values what are resolved automatically.

You can use the Rust's own #[deprecated] attribute on functions to mark it as deprecated and it will reflect to the generated OpenAPI spec. Only parameters has a special deprecated attribute to define them as deprecated.

#[deprecated] attribute supports adding additional details such as a reason and or since version but this is is not supported in OpenAPI. OpenAPI has only a boolean flag to determine deprecation. While it is totally okay to declare deprecated with reason #[deprecated = "There is better way to do this"] the reason would not render in OpenAPI spec.

Doc comment at decorated function will be used for description and summary of the path. First line of the doc comment will be used as the summary and the whole doc comment will be used as description.

/// This is a summary of the operation
///
/// All lines of the doc comment will be included to operation description.
#[salvo_oapi::endpoint()]
fn endpoint() {}

TODO