Crate rustapi_openapi

Crate rustapi_openapi 

Source
Expand description

OpenAPI documentation for RustAPI

This crate provides OpenAPI specification generation and Swagger UI serving for RustAPI applications. It wraps utoipa internally while providing a clean public API.

§Features

  • OpenAPI 3.0.3 and OpenAPI 3.1.0 specification support
  • Swagger UI serving at /docs
  • JSON spec at /openapi.json
  • Schema derivation via #[derive(Schema)]
  • API versioning with multiple strategies (path, header, query, accept)
  • JSON Schema 2020-12 support for OpenAPI 3.1
  • Webhook definitions support

§OpenAPI 3.1 Usage

ⓘ
use rustapi_openapi::v31::{OpenApi31Spec, Webhook, JsonSchema2020};

let spec = OpenApi31Spec::new("My API", "1.0.0")
    .description("API with OpenAPI 3.1 support")
    .webhook("orderPlaced", Webhook::with_summary("Order notification"))
    .schema("User", JsonSchema2020::object()
        .with_property("id", JsonSchema2020::integer())
        .with_property("name", JsonSchema2020::string())
        .with_required("id"))
    .build();

§API Versioning Usage

ⓘ
use rustapi_openapi::versioning::{VersionRouter, ApiVersion, VersionStrategy};

let router = VersionRouter::new()
    .strategy(VersionStrategy::path())
    .default_version(ApiVersion::v1())
    .version(ApiVersion::v1(), VersionedRouteConfig::version(ApiVersion::v1()))
    .version(ApiVersion::v2(), VersionedRouteConfig::version(ApiVersion::v2()));

§Legacy Usage (OpenAPI 3.0)

ⓘ
use rustapi_rs::prelude::*;

#[derive(Serialize, Schema)]
struct User {
    id: i64,
    name: String,
}

RustApi::new()
    .route("/users", get(list_users))
    .docs("/docs")
    .run("127.0.0.1:8080")
    .await

Modules§

utoipa_types
v31
OpenAPI 3.1 specification support
versioning
API Versioning support for OpenAPI

Structs§

ApiInfo
API information for OpenAPI spec
ErrorBodySchema
Error body details
ErrorSchema
Standard error response body
FieldErrorSchema
Field-level validation error
MediaType
Media type in OpenAPI spec
OpenApiConfig
Configuration for OpenAPI documentation
OpenApiSpec
OpenAPI specification builder
Operation
Operation (endpoint) in OpenAPI spec
Parameter
Parameter in OpenAPI spec
PathItem
Path item in OpenAPI spec
RequestBody
Request body in OpenAPI spec
ResponseSpec
Response specification
ValidationErrorBodySchema
Validation error body
ValidationErrorSchema
Validation error response (422)

Enums§

SchemaRef
Schema reference or inline schema

Traits§

IntoParams
Trait used to convert implementing type to OpenAPI parameters.
OperationModifier
Trait for types that can modify an OpenAPI operation
ResponseModifier
Schema
Trait for implementing OpenAPI Schema object.

Functions§

openapi_31_json
Generate OpenAPI 3.1 JSON response
openapi_json
Generate OpenAPI JSON response
swagger_ui_html
Generate Swagger UI HTML response

Derive Macros§

IntoParams
Generate path parameters from struct’s fields.
Schema
Generate reusable OpenAPI schema to be used together with OpenApi.