Crate salvo_oapi

Expand description

OpenAPI support for the Salvo web framework.

This crate provides automatic OpenAPI documentation generation using simple procedural macros. Annotate your handlers and types, and get a complete OpenAPI specification.

§Quick Start

Add the oapi feature to your Salvo dependency
Use #[endpoint] instead of #[handler] on your handlers
Derive ToSchema on your data types
Create an OpenApi instance and mount the Swagger UI

use salvo::prelude::*;
use salvo::oapi::extract::*;

#[derive(ToSchema, serde::Deserialize)]
struct User {
    id: i64,
    name: String,
}

#[endpoint]
async fn get_user(id: PathParam<i64>) -> Json<User> {
    Json(User { id: *id, name: "Alice".into() })
}

#[tokio::main]
async fn main() {
    let router = Router::new()
        .push(Router::with_path("users/<id>").get(get_user));

    let doc = OpenApi::new("My API", "1.0.0").merge_router(&router);

    let router = router
        .push(doc.into_router("/api-doc/openapi.json"))
        .push(SwaggerUi::new("/api-doc/openapi.json").into_router("/swagger-ui"));

    let acceptor = TcpListener::new("127.0.0.1:8080").bind().await;
    Server::new(acceptor).serve(router).await;
}

§Key Traits

Trait	Purpose	Derive Macro
`ToSchema`	Define JSON schema for types	`#[derive(ToSchema)]`
`ToParameters`	Define query/path parameters	`#[derive(ToParameters)]`
`ToResponse`	Define a single response type	`#[derive(ToResponse)]`
`ToResponses`	Define multiple response types	`#[derive(ToResponses)]`

§Documentation UIs

Multiple OpenAPI documentation UIs are available:

UI	Feature Flag	Description
Swagger UI	`swagger-ui`	Interactive API explorer
Scalar	`scalar`	Modern, beautiful API docs
RapiDoc	`rapidoc`	Customizable API documentation
ReDoc	`redoc`	Clean, responsive documentation

§Crate Features

§Serialization

yaml - Enable YAML serialization of OpenAPI objects

§Type Support

chrono - Support for chrono date/time types (DateTime, Date, NaiveDate, Duration)
- DateTime uses format: date-time per RFC3339
- Date and NaiveDate use format: date
time - Support for time crate types (OffsetDateTime, PrimitiveDateTime, Date, Duration)
decimal - Support for rust_decimal::Decimal as String (default)
decimal-float - Support for rust_decimal::Decimal as Number (mutually exclusive with decimal)
uuid - Support for uuid::Uuid with format: uuid
ulid - Support for ulid::Ulid with format: ulid
url - Support for url::Url with format: uri
smallvec - Support for SmallVec (rendered as array)
indexmap - Support for IndexMap (rendered as object)

§Examples

Browse the examples directory for comprehensive examples including:

oapi-hello - Basic OpenAPI setup
oapi-todos - CRUD API with documentation
oapi-upload - File upload documentation

§Learn More

ToSchema - Schema derivation with all attributes
ToParameters - Parameter extraction documentation
ToResponse / ToResponses - Response documentation
[endpoint] - Endpoint macro documentation
Security documentation - API authentication setup

Re-exports§

pub use endpoint::Endpoint;
pub use endpoint::EndpointArgRegister;
pub use endpoint::EndpointOutRegister;

Modules§

endpoint: Enhanced of handler for generate OpenAPI documentation.
extract: Request extractors for the API operation.
info: Implements OpenAPI Metadata types.
naming: Module for name schemas.
operation: Implements OpenAPI Operation Object types.
parameter: Implements OpenAPI Parameter Object types.
path: Implements OpenAPI Path Object types.
rapidocrapidoc: This crate implements necessary boiler plate code to serve RapiDoc via web server. It works as a bridge for serving the OpenAPI documentation created with salvo library in the RapiDoc.
redocredoc: This crate implements necessary boiler plate code to serve ReDoc via web server. It works as a bridge for serving the OpenAPI documentation created with salvo library in the ReDoc.
request_body: Implements OpenAPI Request Body types.
response: Implements OpenApi Responses.
scalarscalar: This crate implements necessary boiler plate code to serve Scalar via web server. It works as a bridge for serving the OpenAPI documentation created with salvo library in the Scalar.
schema: Implements OpenAPI Schema Object types which can be used to define field properties, enum values, array or object types.
security: Implements OpenAPI Security Schema types.
server: Implements OpenAPI Server Object types to configure target servers.
swagger_uiswagger-ui: This crate implements necessary boiler plate code to serve Swagger UI via web server. It works as a bridge for serving the OpenAPI documentation created with salvo library in the Swagger UI.

Structs§

Array: Array represents Vec or slice type of items.
Components: Implements OpenAPI Components Object which holds supported reusable objects.
Contact: OpenAPI Contact information of the API.
Content: Content holds request body content or response content.
Discriminator: OpenAPI Discriminator object which can be optionally used together with OneOf composite object.
Example: Implements OpenAPI Example Object.
ExternalDocs: Reference of external resource allowing extended documentation.
Header: Implements OpenAPI Header Object for response headers.
Info: Examples
License: OpenAPI License information of the API.
Object: Implements subset of OpenAPI Schema Object which allows adding other Schemas as properties to this Schema.
OpenApi: Root object of the OpenAPI document.
Operation: Implements OpenAPI Operation Object object.
Operations: Collection for save Operations.
Parameter: Implements OpenAPI Parameter Object for Operation.
Parameters: Collection for OpenAPI Parameter Objects.
PathItem: Implements OpenAPI Path Item Object what describes Operations available on a single path.
Paths: Implements OpenAPI Path Object types.
Ref: Implements OpenAPI Reference Object that can be used to reference reusable components such as Schemas or Responses.
RequestBody: Implements OpenAPI Request Body.
Response: Implements OpenAPI Response Object.
Responses: Implements OpenAPI Responses Object.
Schemas: Schemas collection for OpenApi.
SecurityRequirement: OpenAPI security requirement object.
Server: Represents target server object. It can be used to alter server connection for path operations.
ServerVariable: Implements OpenAPI Server Variable used to substitute variables in Server::url.
ServerVariables: Server Variables information for OpenApi.
Servers: Collection for Server objects.
Tag: Implements OpenAPI Tag Object.
Xml: Implements OpenAPI Xml Object.

Enums§

BasicType: Represents data type fragment of Schema.
Deprecated: Value used to indicate whether reusable schema, parameter or operation is deprecated.
KnownFormat: Known schema format modifier property to provide fine detail of the primitive type.
OpenApiVersion: Represents available OpenAPI versions.
ParameterIn: In definition of Parameter.
ParameterStyle: Defines how Parameter should be serialized.
PathItemType: Path item operation type.
RefOr: A Ref or some other type T.
Required: Value used to indicate whether parameter or property is required.
Schema: Is super type for OpenAPI Schema Object. Schema is reusable resource what can be referenced from path operations and other components using Ref.
SchemaFormat: Additional format for SchemaType to fine tune the data type used.
SchemaType: Represents type of Schema.
SecurityScheme: OpenAPI security scheme for path operations.

Traits§

RouterExt: Router extension trait for openapi metadata.
ToParameter: Trait used to give Parameter information for OpenAPI.
ToParameters: Trait used to convert implementing type to OpenAPI parameters.
ToRequestBody: This trait is implemented to document a type (like an enum) which can represent request body, to be used in operation.
ToResponse: This trait is implemented to document a type which represents a single response which can be referenced or reused as a component in multiple operations.
ToResponses: This trait is implemented to document a type (like an enum) which can represent multiple responses, to be used in operation.
ToSchema: Trait for implementing OpenAPI Schema object.

Type Aliases§

PathMappreserve-path-order: The structure of the internal storage object paths.
PropMappreserve-prop-order: The structure of the internal storage object properties.
TupleUnit: Represents nullable type.

Attribute Macros§

endpoint: Enhanced of handler for generate OpenAPI documentation.

Derive Macros§

ToParameters: Generate parameters from struct’s fields.
ToResponse: Generate reusable OpenApi response.
ToResponses: Generate responses with status codes what can be used in OpenApi.
ToSchema: This is #[derive] implementation for ToSchema trait.

Crate salvo_oapi

Crate salvo_oapi Copy item path

§Quick Start

§Key Traits

§Documentation UIs

§Crate Features

§Serialization

§Type Support

§Examples

§Learn More

Re-exports§

Modules§

Structs§

Enums§

Traits§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate salvo_oapi