Product OS : Openapi

Product OS : OpenAPI provides a set of structs for defining the structure of an OpenAPI / Swagger specification. This crate is no_std compatible and requires the 'openapi' feature for serialization/deserialization support. Intended to be used with Product OS : Connector.

What is Product OS?

Product OS is a collection of packages that provide different tools and features that can work together to build products more easily for the Rust ecosystem.

Feature Flags

default features: std, openapi

Installation

[dependencies]
product-os-openapi = "0.0.1"

Pin the version to match the crate Cargo.toml when using path or git dependencies.

Documentation

Full API documentation is available at docs.rs/product-os-openapi.

Usage

Overview

A no_std compatible Rust library for working with OpenAPI/Swagger specifications.

Features

• Dual Version Support: Works with both Swagger 2.0 and OpenAPI 3.x specifications
• no_std Compatible: Can be used in embedded and constrained environments
• Type Safety: Strongly typed structs with proper validation through the type system
• Serde Integration: Full JSON serialization/deserialization support
• Well Documented: Comprehensive rustdoc documentation with examples
• Zero Unsafe Code: Pure safe Rust implementation

Installation

Add this to your Cargo.toml:

[dependencies]
product-os-openapi = "0.0.5"

Or use cargo add:

cargo add product-os-openapi

Usage

Parsing OpenAPI v3 Specification

use product_os_openapi::ProductOSOpenAPI;
use serde_json;

let json = r#"{
    "openapi": "3.0.0",
    "info": {
        "title": "My API",
        "version": "1.0.0"
    },
    "paths": {
        "/users": {
            "get": {
                "summary": "List users",
                "responses": {
                    "200": {
                        "description": "Success"
                    }
                }
            }
        }
    }
}"#;

let spec: ProductOSOpenAPI = serde_json::from_str(json)?;

assert_eq!(spec.info.title, "My API");
assert!(spec.is_openapi_v3());
assert_eq!(spec.version(), Some("3.0.0"));

Parsing Swagger v2 Specification

use product_os_openapi::ProductOSOpenAPI;
use serde_json;

let json = r#"{
    "swagger": "2.0",
    "info": {
        "title": "My API",
        "version": "1.0.0"
    },
    "host": "api.example.com",
    "basePath": "/v1",
    "paths": {}
}"#;

let spec: ProductOSOpenAPI = serde_json::from_str(json)?;

assert!(spec.is_swagger_v2());
assert_eq!(spec.host, Some("api.example.com".to_owned()));

Creating Specifications Programmatically

use product_os_openapi::{ProductOSOpenAPI, Info, Server};

let spec = ProductOSOpenAPI {
    openapi: Some("3.0.0".to_owned()),
    info: Info {
        title: "My API".to_owned(),
        version: "1.0.0".to_owned(),
        description: Some("A sample API".to_owned()),
        summary: None,
        terms_of_service: None,
        contact: None,
        license: None,
    },
    servers: Some(vec![Server {
        url: "https://api.example.com".to_owned(),
        description: Some("Production server".to_owned()),
        variables: None,
    }]),
    paths: None,
    webhooks: None,
    components: None,
    definitions: None,
    security: None,
    tags: None,
    external_docs: None,
    json_schema_dialect: None,
    swagger: None,
    host: None,
    base_path: None,
    schemes: None,
    consumes: None,
    produces: None,
};

let json = serde_json::to_string_pretty(&spec)?;

OpenAPI v2 vs v3

This crate supports both versions by including fields from both specifications:

OpenAPI v3 Specific Fields

• openapi - Version string (e.g., "3.0.0")
• servers - Server connectivity information
• components - Reusable components
• webhooks - Incoming webhook definitions (v3.1+)
• json_schema_dialect - JSON Schema dialect URI (v3.1+)

Swagger v2 Specific Fields

• swagger - Version string (must be "2.0")
• host - API host
• base_path - Base path for endpoints
• schemes - Transfer protocols
• consumes - Global MIME types consumed
• produces - Global MIME types produced
• definitions - Data type definitions

Shared Fields (Both Versions)

• info - API metadata (required)
• paths - API paths and operations
• security - Security requirements
• tags - Tag definitions
• external_docs - External documentation

Helper Methods

The library provides convenient helper methods:

// Check specification version
if spec.is_openapi_v3() {
    println!("This is OpenAPI v3");
}

if spec.is_swagger_v2() {
    println!("This is Swagger v2");
}

// Get version string
if let Some(version) = spec.version() {
    println!("Spec version: {}", version);
}

Performance

Benchmarks on a modern CPU show:

• Deserialization: ~6µs per operation
• Serialization: ~3µs per operation

Run benchmarks with:

cargo bench

no_std Support

This crate is no_std compatible. When using without the standard library, you need to enable the openapi feature which provides alloc support:

[dependencies]
product-os-openapi = { version = "0.0.5", default-features = false, features = ["openapi"] }

Features

• default - Enables std and openapi features
• std - Enables standard library support
• openapi - Enables serde serialization/deserialization (requires alloc)

Related Crates

This crate is part of the Product OS ecosystem and is designed to work with:

• product-os-connector - Framework for defining APIs using OpenAPI specs

Documentation

Full documentation is available at docs.rs/product-os-openapi.

Contributing

Contributions are not currently available but will be available on a public repository soon.

License

This project is licensed under the GNU GPLv3.