oasert 0.1.4

A library for verifying in-flight requests against a provided OpenAPI 3.1.x or 3.0.x specification.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# OASert

**OASert** is a high-performance Rust library for runtime validation of HTTP requests against OpenAPI 3.x specifications. It provides a comprehensive suite of tools for traversing, validating, and caching OpenAPI document structures to
ensure strict compliance with defined API contracts during request processing.

[![codecov](https://codecov.io/gh/idemio/OASert/branch/main/graph/badge.svg)](https://codecov.io/gh/idemio/OASert)
[![CI Status](https://github.com/idemio/OASert/workflows/Rust/badge.svg)](https://github.com/idemio/OASert/actions)

---

## Core Capabilities

- **Comprehensive Request Validation**  
  Performs rigorous validation of HTTP request elements (payloads, headers, query parameters, path parameters) against OpenAPI v3.x specifications, ensuring complete compliance with defined schemas.

- **High-Performance Validator Caching**  
  Implements a thread-safe, concurrent caching infrastructure powered by `DashMap` (v7.0) that minimizes redundant validator instantiations and optimizes memory usage.

- **Advanced Specification Traversal**  
  Provides sophisticated algorithms for navigating complex OpenAPI documents, with robust handling of nested `$ref` references through pointer resolution and circular reference detection.

- **Validation Error Reporting**  
  Detailed error reporting with specific categories like missing properties, invalid types, or unsupported schema versions.

- **Supports OpenAPI Drafts**  
  Includes support for both OpenAPI 3.0.x (Draft 4) and OpenAPI 3.1.x (Draft 2020-12).

---

## Installation

Add `OASert` to your `Cargo.toml`:

```toml 
[dependencies]
oasert = "0.1.1"
``` 

---

## Basic Usage

### Initializing the Validator

1. Parse your OpenAPI specification into a `serde_json::Value`.
2. Create an `OpenApiPayloadValidator` using the parsed specification.
3. Pass incoming requests to the validator

See a full example using hyper [here](./examples/hyper-validation/main.rs)
See a full example using AWS Lambda [here](./examples/aws-lambda-http-validation/main.rs)

## Components

### 1. `ValidatorCache`

Efficient caching mechanism for validators to avoid repeated instantiations.

- Insert or retrieve validators dynamically.
- Clear the cache when needed.
- Automatically create validators for specific IDs if not cached.

### 2. `OpenApiTraverser`

Utility class to traverse OpenAPI specifications with support for:

- Resolving `$ref` pointers.
- Fetching required or optional specification nodes.
- Handling complex paths and parameters.

### 3. `OpenApiTypes`

Type mapping utility to convert OpenAPI types (`string`, `boolean`, etc.) into native Rust types.

### 4. Error Handling

Comprehensive error handling for:

- Missing parameters or fields.
- Unsupported specification versions.
- Invalid schema values or types.