# Product OS : Openapi
[](https://crates.io/crates/product-os-openapi)
[](https://docs.rs/product-os-openapi)
[](https://www.rust-lang.org)
[](https://www.gnu.org/licenses/gpl-3.0)
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
| `openapi` | yes | Enables: serde, serde/derive, serde_json, serde_json/alloc |
| `std` | yes | Enables: no-std-compat/std, openapi |
**`default` features:** `std`, `openapi`
## Installation
```toml
[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](https://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`:
```toml
[dependencies]
product-os-openapi = "0.0.5"
```
Or use cargo add:
```bash
cargo add product-os-openapi
```
## Usage
### Parsing OpenAPI v3 Specification
```rust
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
```rust
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
```rust
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:
```rust
// 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:
```bash
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:
```toml
[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](https://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](https://choosealicense.com/licenses/gpl-3.0/).