OpenAPI Specification (OAS) 3.0 for Rust

A comprehensive Rust implementation of the OpenAPI Specification 3.0 with full serialization/deserialization support and convenient builder patterns for programmatic API specification creation.

Features

• ✅ Complete OAS 3.0 Support - All OpenAPI 3.0 specification features
• 🔄 Serde Integration - Full JSON/YAML serialization and deserialization
• 🛠️ Builder Patterns - Fluent APIs for easy specification construction
• 🔒 Type Safety - Leverages Rust's type system to prevent invalid specifications
• 📚 Reference System - Support for both inline definitions and $ref references
• 🚀 Convenience Methods - Extensive helper functions to reduce boilerplate

Quick Start

Add this to your Cargo.toml:

[dependencies]
oas = "0.2"
serde_json = "1.0"  # For JSON serialization

Basic Example

use oas::{builders, Referenceable, PathItem, Tag, Server};

fn main() {
    let api = builders::api("Pet Store API", "1.0.0")
        .with_description("A sample Pet Store API")
        .add_server(Server::new("https://api.petstore.com"))
        .add_tag(Tag::with_description("pets", "Pet operations"))
        .add_path("/pets", PathItem::new()
            .with_get(builders::get("List all pets")
                .tag("pets")
                .parameter(Referenceable::query_param("limit")
                    .with_schema(Referenceable::integer_schema()))
                .build())
            .with_post(builders::post("Create a pet")
                .tag("pets")
                .request_body(Referenceable::json_body(
                    Referenceable::schema_ref("Pet")))
                .build()));

    println!("{}", api.to_string());
}

Core Concepts

Referenceable Types

The Referenceable<T> type is central to OpenAPI specifications, allowing you to use either inline data or references to reusable components:

use oas::{Referenceable, Schema};

// Inline schema
let inline = Referenceable::data(Schema::string());

// Reference to a component
let reference = Referenceable::schema_ref("User");

// Component reference with custom path
let custom_ref = Referenceable::component_ref("schemas", "CustomType");

Builder Pattern

Use the builder pattern for complex operations:

use oas::{builders, Referenceable};

let operation = builders::get("Get user by ID")
    .tag("users")
    .operation_id("getUserById")
    .parameter(Referenceable::path_param("userId")
        .with_schema(Referenceable::string_schema())
        .with_description("The ID of the user to retrieve"))
    .response("200", Referenceable::ok("User retrieved successfully"))
    .response("404", Referenceable::error("User not found"))
    .build();

Schema Creation

Create schemas with type-specific constructors:

use oas::{Schema, Referenceable};

// Basic types
let string_schema = Schema::string();
let integer_schema = Schema::integer();
let boolean_schema = Schema::boolean();

// Or as Referenceable for use in parameters/responses
let ref_schema = Referenceable::string_schema();

Examples

Complete API Specification

use oas::{builders, Referenceable, PathItem, Tag, Server, Components, Schema};
use std::collections::BTreeMap;

let mut schemas = BTreeMap::new();
schemas.insert("User".to_string(), Referenceable::data(
    Schema::object()
        .with_description("A user object")
));

let api = builders::api("User Management API", "2.0.0")
    .with_description("API for managing users")
    .add_server(Server::new("https://api.example.com/v2")
        .with_description("Production server"))
    .add_server(Server::new("https://staging.api.example.com/v2")
        .with_description("Staging server"))
    .with_components(Components::new()
        .with_schemas(schemas))
    .add_tag(Tag::with_description("users", "User management operations"))
    .add_path("/users", PathItem::new()
        .with_get(builders::get("List users")
            .tag("users")
            .parameter(Referenceable::query_param("page")
                .with_schema(Referenceable::integer_schema())
                .with_description("Page number"))
            .parameter(Referenceable::query_param("limit")
                .with_schema(Referenceable::integer_schema())
                .with_description("Items per page"))
            .build())
        .with_post(builders::post("Create user")
            .tag("users")
            .request_body(Referenceable::json_body(
                Referenceable::schema_ref("User")))
            .build()))
    .add_path("/users/{id}", PathItem::new()
        .with_get(builders::get("Get user")
            .tag("users")
            .parameter(Referenceable::path_param("id")
                .with_schema(Referenceable::string_schema()))
            .build())
        .with_put(builders::put("Update user")
            .tag("users")
            .parameter(Referenceable::path_param("id")
                .with_schema(Referenceable::string_schema()))
            .request_body(Referenceable::json_body(
                Referenceable::schema_ref("User")))
            .build())
        .with_delete(builders::delete("Delete user")
            .tag("users")
            .parameter(Referenceable::path_param("id")
                .with_schema(Referenceable::string_schema()))
            .build()));

println!("{}", serde_json::to_string_pretty(&api).unwrap());

Loading from JSON

use oas::OpenAPIV3;

let json_spec = r#"{
    "openapi": "3.0.0",
    "info": {
        "title": "Sample API",
        "version": "1.0.0"
    },
    "paths": {}
}"#;

let spec: OpenAPIV3 = serde_json::from_str(json_spec).unwrap();
println!("Loaded API: {}", spec.info.title);

API Reference

Quick Builders

• builders::api(title, version) - Create a new API specification
• builders::get(summary) - GET operation with 200 response
• builders::post(summary) - POST operation with 201/400 responses
• builders::put(summary) - PUT operation with 200/404 responses
• builders::delete(summary) - DELETE operation with 204/404 responses

Referenceable Helpers

• Referenceable::data(item) - Wrap inline data
• Referenceable::reference(ref_str) - Create reference
• Referenceable::schema_ref(name) - Schema component reference
• Referenceable::query_param(name) - Query parameter
• Referenceable::path_param(name) - Path parameter (automatically required)
• Referenceable::json_body(schema) - JSON request body

Schema Shortcuts

• Schema::string(), Schema::integer(), Schema::boolean()
• Schema::array(), Schema::object()
• Referenceable::string_schema(), Referenceable::integer_schema(), etc.

Testing

The crate includes comprehensive tests using real OpenAPI specification files:

cargo test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.