{"id":14986701,"url":"https://github.com/nawaz1991/cpp-oasvalidator","last_synced_at":"2025-10-10T17:15:31.361Z","repository":{"id":201056125,"uuid":"697365339","full_name":"nawaz1991/cpp-oasvalidator","owner":"nawaz1991","description":"A FAST C++ library to validate the HTTP requests against the OpenAPI specifications of the REST server.","archived":false,"fork":false,"pushed_at":"2024-07-11T08:00:10.000Z","size":13504,"stargazers_count":16,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-25T18:21:23.564Z","etag":null,"topics":["api","cpp","cpp11","json-schema-validator","json-validate","json-validation","json-validator","oas","openapi","openapi-validation","openapi-validator","parameter-validation","rapidjson","rest","rest-validators","restful","schema-validator","swagger","validation","validator"],"latest_commit_sha":null,"homepage":"https://nawaz1991.github.io/cpp-oasvalidator/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nawaz1991.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-27T15:23:03.000Z","updated_at":"2024-12-06T16:16:31.000Z","dependencies_parsed_at":"2023-12-14T18:17:45.204Z","dependency_job_id":"3afa471c-b3c6-4484-af32-424121eefeeb","html_url":"https://github.com/nawaz1991/cpp-oasvalidator","commit_stats":{"total_commits":43,"total_committers":1,"mean_commits":43.0,"dds":0.0,"last_synced_commit":"29f5410bef6a73c19d9ad605dc4819abf6394f61"},"previous_names":["nawaz1991/cpp-oasvalidator"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nawaz1991%2Fcpp-oasvalidator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nawaz1991%2Fcpp-oasvalidator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nawaz1991%2Fcpp-oasvalidator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nawaz1991%2Fcpp-oasvalidator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nawaz1991","download_url":"https://codeload.github.com/nawaz1991/cpp-oasvalidator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248476472,"owners_count":21110291,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cpp","cpp11","json-schema-validator","json-validate","json-validation","json-validator","oas","openapi","openapi-validation","openapi-validator","parameter-validation","rapidjson","rest","rest-validators","restful","schema-validator","swagger","validation","validator"],"created_at":"2024-09-24T14:13:22.681Z","updated_at":"2025-10-10T17:15:26.317Z","avatar_url":"https://github.com/nawaz1991.png","language":"C++","readme":"cpp-oasvalidator: REST Request Validator\n============================================\n\n[![Language C++](https://img.shields.io/badge/language-c++-blue.svg?logo=c%2B%2B)](https://isocpp.org)\n[![Github releases](https://img.shields.io/github/release/nawaz1991/cpp-oasvalidator.svg)](https://github.com/nawaz1991/cpp-oasvalidator/releases)\n![Mac build](https://img.shields.io/github/actions/workflow/status/nawaz1991/cpp-oasvalidator/mac-build.yml?logo=apple\u0026label=Tests)\n![Linux build](https://img.shields.io/github/actions/workflow/status/nawaz1991/cpp-oasvalidator/linux-build.yml?logo=linux\u0026label=Tests)\n![Win build](https://img.shields.io/github/actions/workflow/status/nawaz1991/cpp-oasvalidator/windows-build.yml?logo=windows\u0026label=Tests)\n[![codecov](https://codecov.io/gh/nawaz1991/cpp-oasvalidator/branch/main/graph/badge.svg?token=96b475c2-8dc1-4693-8ce3-84a572720d43)](https://codecov.io/gh/nawaz1991/cpp-oasvalidator)\n[![License](https://img.shields.io/github/license/nawaz1991/cpp-oasvalidator.svg)](./LICENSE)\n[![API Docs](https://img.shields.io/badge/API%20Docs-v1.1.1-brightgreen)](API.md)\n[![Benchmark](https://img.shields.io/badge/Benchmark-brightgreen)](https://nawaz1991.github.io/cpp-oasvalidator/benchmark.html)\n\n\n`cpp-oasvalidator` is a C++ thread-safe library engineered for the validation of HTTP requests against OpenAPI 3.x specifications. This library can be integrated with REST servers and API gateways to ensure only compliant requests reach your backend services.\n\nWith support for OpenAPI 3.x, this library streamlines the process of validating various components of an HTTP request, from methods and routes to detailed parameters and `JSON` body.\n\n## Table of Contents\n1. [Key Features](#1-key-features-)\n2. [Validation Sequence](#2-validation-sequence-)\n3. [Parameter Styles, data types \u0026 Deserialization Support](#3-parameter-styles-data-types--deserialization-)\n   1. [Path Parameters](#31-path-parameters)\n   2. [Query Parameters](#32-query-parameters)\n   3. [Header Parameters](#33-header-parameters)\n4. [Error Handling](#4-error-handling-)\n5. [Getting Started](#5-getting-started-)\n    1. [Installation](#51-installation-)\n        1. [Cloning the Repository](#511-cloning-the-repository)\n        2. [Building and Installing](#512-building-and-installing)\n        3. [Running the Tests](#513-running-the-tests)\n        4. [Generating Code Coverage Report](#514-generating-code-coverage-report)\n        5. [Performance Benchmarking](#515-performance-benchmarking)\n        6. [Running the Example](#516-running-the-example)\n    2. [Initialization](#52--initialization-)\n6. [Conclusion](#6-conclusion-)\n7. [License](#7-license-)\n\n## 1. Key Features 🌟\n- **Efficient, Sequential Validation**: Validates requests in a logical order, starting from the HTTP method down to the header parameters. This means if you validate a later stage, preceding steps are validated as well.\n- **Thread-Safe**: Utilizes thread-safe data structures and methods to ensure concurrent requests are handled without any issues.\n- **In-Depth Error Reports**: Returns an insightful error enumeration coupled with an extensive error message in JSON format to pinpoint inaccuracies.\n- **Optimized Performance**: Utilizes lazy deserialization, only processing content when all prior checks pass.\n- **Broad Parameter Support**: Deserializes parameters across a spectrum of styles and data types, ensuring a wide range of OpenAPI configurations are supported.\n\nBenchmarking results are available [here](https://nawaz1991.github.io/cpp-oasvalidator/benchmark.html).\n\n## 2. Validation Sequence 📜\nThe library validates HTTP requests in the following order:\n\n1. **HTTP Method Validation**: Ensures that the HTTP method (GET, POST, PUT, etc.) aligns with the OpenAPI spec.\n2. **Route Validation**: Checks if the provided route matches the specification.\n3. **Body Validation**: Validates the JSON body structure and data against the OpenAPI spec.\n4. **Path Parameter Validation**: Validates path parameters.\n5. **Query Parameter Validation**: Ensures query parameters are consistent with the OpenAPI spec.\n6. **Header Parameter Validation**: Confirms headers are in line with the OpenAPI specification.\n7. **Request Validation**: Validates the whole HTTP request starting from method, route, body (if provided), path/query params (if specified in specs) and/or headers. To address all variations, four overloaded methods are provided.\n\nFor a comprehensive understanding, refer to [API Reference](API.md).\n\n## 3. Parameter Styles, data types \u0026 Deserialization 🛠\n`cpp-oasvalidator` can deserialize and parse parameters of all data types serialized in various styles provided by Swagger/OpenAPI. Following tables provide the details.\n\n### 3.1 Path Parameters\n| **Style** | **Explode** | **Primitive** | **String** | **Array of primitives** | **Array of strings** | **Object** |\n|:---------:|:-----------:|:-------------:|:----------:|:-----------------------:|:--------------------:|:----------:|\n|  simple*  |   false*    |       ✅       |     ✅      |            ✅            |          ✅           |     ✅      |\n|  simple   |    true     |       ✅       |     ✅      |            ✅            |          ✅           |     ✅      |\n|   label   |    false    |       ✅       |     ✅      |            ✅            |          ✅           |     ✅      |\n|   label   |    true     |       ✅       |     ✅      |            ✅            |          ✅           |     ✅      |\n|  matrix   |    false    |       ✅       |     ✅      |            ✅            |          ✅           |     ✅      |\n|  matrix   |    true     |       ✅       |     ✅      |            ✅            |          ✅           |     ✅      |\n\n\u0026#42; Default serialization method\n\n### 3.2 Query Parameters\n|   **Style**    | **Explode** | **Primitive** | **String** | **Array of primitives** | **Array of strings** | **Object** |\n|:--------------:|:-----------:|:-------------:|:----------:|:-----------------------:|:--------------------:|:----------:|\n|     form*      |    true*    |       ✅       |     ✅      |            ✅            |          ✅           |     ✅      |\n|      form      |    false    |       ✅       |     ✅      |            ✅            |          ✅           |     ✅      |\n| spaceDelimited |    true     |      N/A      |    N/A     |            ✅            |          ✅           |    N/A     |\n| spaceDelimited |    false    |      N/A      |    N/A     |            ✅            |          ✅           |    N/A     |\n| pipeDelimited  |    true     |      N/A      |    N/A     |            ✅            |          ✅           |    N/A     |\n| pipeDelimited  |    false    |      N/A      |    N/A     |            ✅            |          ✅           |    N/A     |\n|   deepObject   |    false    |      N/A      |    N/A     |           N/A           |         N/A          |     ✅      |\n\n\u0026#42; Default serialization method\n\n### 3.3 Header Parameters\n| **Style** | **Explode** | **Primitive** | **String** | **Array of primitives** | **Array of strings** | **Object** |\n|:---------:|:-----------:|:-------------:|:----------:|:-----------------------:|:--------------------:|:----------:|\n|  simple*  |   false*    |       ✅       |     ✅      |            ✅            |          ✅           |     ✅      |\n|  simple   |    true     |       ✅       |     ✅      |            ✅            |          ✅           |     ✅      |\n\n\u0026#42; Default serialization method\n\n##  4. Error Handling 🚫\n\ncpp-oasvalidator responds with a specific `validationError` enum value, indicating the error type:\n\n```cpp\nenum class validationError\n{\n    NONE                 = 0,\n    INVALID_METHOD       = -1,\n    INVALID_ROUTE        = -2,\n    INVALID_PATH_PARAM   = -3,\n    INVALID_QUERY_PARAM  = -4,\n    INVALID_HEADER_PARAM = -5,\n    INVALID_BODY         = -6,\n    INVALID_RSP          = -7\n};\n```\n\nAn accompanying detailed error message, structured in JSON, elucidates the error:\n\n```JSON\n{\n   \"errorCode\": \"INVALID_BODY\",\n   \"details\": {\n      \"specRef\": \"#/paths/%2Ftest%2Fall%2F{param1}%2Fabc%2F{param2}%2F{param3}/post/requestBody/content/application%2Fjson/schema\",\n      \"code\": \"oneOf\",\n      \"description\": \"Property did not match any of the sub-schemas specified by 'oneOf', refer to following errors.\",\n      \"instance\": \"#/field6\",\n      \"schema\": \"#/properties/field6\",\n      \"errors\": [\n         {\n            \"code\": \"type\",\n            \"description\": \"Property has a type 'boolean' that is not in the following list: 'integer'.\",\n            \"instance\": \"#/field6\",\n            \"schema\": \"#/properties/field6/oneOf/0\",\n            \"context\": \"oneOf\"\n         },\n         {\n            \"code\": \"type\",\n            \"description\": \"Property has a type 'boolean' that is not in the following list: 'string'.\",\n            \"instance\": \"#/field6\",\n            \"schema\": \"#/properties/field6/oneOf/1\",\n            \"context\": \"oneOf\"\n         }\n      ]\n   }\n}\n```\n\n\n## 5. Getting Started 🚀\n\n### 5.1 Installation 🔧\n\n**Prerequisites:**\n- A C++11 compatible compiler.\n- CMake 3.10 or higher.\n- GoogleTest (for tests and code coverage)\n- GCOV (for code covarge report)\n- LCOV (for code covarge report)\n\nAlthough `cpp-oasvalidator` utilizes RapidJSON during its build process, the final build is standalone and doesn't require any additional dependencies at runtime.\n\n#### 5.1.1 Cloning the Repository\nTo clone the repository, run the following command:\n\n```bash\ngit clone --recursive https://github.com/nawaz1991/cpp-oasvalidator.git\n```\n\n\n#### 5.1.2 Building and Installing\n\nTo build and install `cpp-oasvalidator`, follow the steps below:\n\n1. Navigate to the root directory of the project.\n2. Run the following commands:\n   ```bash\n    cmake -S . -B build \n    cmake --build build --target oasvalidator -j $(nproc)\n    cd build\n    sudo make install\n   ```\n\n#### 5.1.3 Running the Tests\n\nTo run the tests, follow the steps below:\n1. Navigate to the root directory of the project.\n2. Run the following commands:\n   ```bash\n    cmake -S . -B build -DBUILD_TESTS=ON\n    cmake --build build --target oasvalidator-unittests -j $(nproc)\n    build/test/unittest/oasvalidator-unittests\n    ```\n\n#### 5.1.4 Generating Code Coverage Report\n\nTo generate the code coverage report, follow the steps below:\n1. Navigate to the root directory of the project.\n2. Run the following commands:\n   ```bash\n    cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_COVERAGE=ON\n    cmake --build build --target covhtml-oasvalidator -j $(nproc)\n    ```\n    The coverage report will be generated in the `build/covhtml-cpp-oasvalidator/` directory. Open `index.html` in your browser to view the report.\n\n### 5.1.5 Performance Benchmarking\n\nTo run the performance benchmark, follow the steps below:\n\n1. Navigate to the root directory of `cpp-oasvalidator`.\n2. Run the following commands:\n   ```bash\n    cmake -S . -B build -DBUILD_PERF=ON\n    cmake --build build --target oasvalidator-perftests -j $(nproc)\n    build/test/perftest/oasvalidator-perftests\n    ```\n\n#### 5.1.6 Running the Example\n\nTo run the example, follow the steps below:\n\n1. Navigate to the root directory of `cpp-oasvalidator`.\n2. Run the following commands:\n   ```bash\n    cmake -S . -B build -DBUILD_EXAMPLE=ON\n    cmake --build build --target oasvalidator-example -j $(nproc)\n    build/example/oasvalidator-example\n    ```\n\n### 5.1.7 Generating API Documentation\n\nTo generate the API documentation, follow the steps below:\n\n1. Navigate to the root directory of `cpp-oasvalidator`.\n2. Run the following commands:\n   ```bash\n    cmake -S . -B build -DBUILD_DOCS=ON\n    cmake --build build --target docs -j $(nproc)\n    ```\n    The documentation will be generated in the `build/doc/html` directory. Open `index.html` in your browser to view the documentation.\n\n### 5.2  Initialization 🎬\nTo utilize `cpp-oasvalidator`, link the library and include the relevant header and initialize the validator with your OpenAPI specification:\n\n```cmake\ntarget_link_libraries(\u003cyour-target\u003e oasvalidator)\n```\n\n```cpp\n#include \u003coas_validator.hpp\u003e\nOASValidator validator(\"/path/to/your/spec.json\");\n```\n\n\u003e Note: The `oas_specs` can be a file path or a JSON string. If you provide a file path, the library will read the file and parse it. If you provide a JSON string, the library will parse it directly.\n\nThen, utilize the various validation methods to inspect your requests.\n\nFor a detailed breakdown of each API, refer to the [API Reference](API.md) or the [example](example/example.cpp) provided in the repository.\n\n##  6. Conclusion 📜\ncpp-oasvalidator is your one-stop solution for rigorous REST request validation against the OpenAPI specification. With its systematic validation order, expansive parameter style support, and meticulous error reporting, it ensures your services stay compliant with your OpenAPI specs.\n\n## 7. License 📄\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for the full license text.\n\n© 2024 Muhammad Nawaz. All Rights Reserved.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnawaz1991%2Fcpp-oasvalidator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnawaz1991%2Fcpp-oasvalidator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnawaz1991%2Fcpp-oasvalidator/lists"}