{"id":16929334,"url":"https://github.com/hslatman/caddy-openapi-validator","last_synced_at":"2025-04-11T18:07:50.648Z","repository":{"id":57541418,"uuid":"286259419","full_name":"hslatman/caddy-openapi-validator","owner":"hslatman","description":"A Caddy HTTP handler for validating requests and responses against an OpenAPI specification","archived":false,"fork":false,"pushed_at":"2024-11-13T10:35:27.000Z","size":6967,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-11T18:06:23.391Z","etag":null,"topics":["caddy","caddyserver","hacktoberfest","openapi","openapi3"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hslatman.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":"2020-08-09T15:02:31.000Z","updated_at":"2024-08-28T06:43:30.000Z","dependencies_parsed_at":"2025-02-19T22:31:17.200Z","dependency_job_id":"45a64f5a-4b61-4d00-8a92-296d38acef47","html_url":"https://github.com/hslatman/caddy-openapi-validator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hslatman%2Fcaddy-openapi-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hslatman%2Fcaddy-openapi-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hslatman%2Fcaddy-openapi-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hslatman%2Fcaddy-openapi-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hslatman","download_url":"https://codeload.github.com/hslatman/caddy-openapi-validator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248456370,"owners_count":21106603,"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":["caddy","caddyserver","hacktoberfest","openapi","openapi3"],"created_at":"2024-10-13T20:39:05.581Z","updated_at":"2025-04-11T18:07:50.622Z","avatar_url":"https://github.com/hslatman.png","language":"Go","readme":"# Caddy OpenAPI Validator (WIP)\n\nA [Caddy](https://caddyserver.com/) module that validates requests and responses against an [OpenAPI](https://www.openapis.org/) specification.\n\n## Description\n\nThe OpenAPI Validator module is a [Caddy](https://caddyserver.com/) HTTP handler that validates requests and responses against an OpenAPI specification.\nThe [kin-openapi](https://github.com/getkin/kin-openapi) `openapi3filter` library performs the actual validation.\nThe handler in this repository is a small wrapper for the functionality provided by `openapi3filter`, with basic configuration and integrations options for Caddy. \nThe project is currently in POC stage, meaning that much of it can, and likely will, change.\n\nThe request/response flow is as follows:\n\n* When a request arrives, the Validator will look for a valid route in the provided OpenAPI specification and validate the request against the schema.\n* The request is then passed on to the next HTTP handler in the chain and the Validator will wait for its response.\n* After capturing the response, the Validator will validate the response to be valid.\n* If no errors occurred during the validation, the response will be returned.\n\n## Usage\n\nThe simplest way to use the OpenAPI Validator HTTP handler is by using [xcaddy](https://github.com/caddyserver/xcaddy):\n\n```bash\n$ xcaddy build v2.1.1 --with github.com/hslatman/caddy-openapi-validator\n```\n\nAlternatively, the HTTP handler can be included as a Caddy module as follows:\n\n```golang\nimport (\n\t_ \"github.com/hslatman/caddy-openapi-validator\"\n)\n```\n\nConfigure the OpenAPI Validator handler as one of the handlers to be executed by Caddy (in [JSON config](https://caddyserver.com/docs/json/) format):\n\n```json\n    ...\n        \"handle\": [\n            {\n                \"handler\": \"openapi_validator\",\n                \"filepath\": \"examples/petstore.yaml\",\n                \"validate_routes\": true,\n                \"validate_requests\": true,\n                \"validate_responses\": true,\n                \"validate_servers\": true,\n                \"validate_security\": true,\n                \"path_prefix_to_be_trimmed\": \"\",\n                \"additional_servers\": [\"\"],\n                \"enforce\": true,\n                \"log\": true\n            }\n        ]\n    ...\n```\n\nThe OpenAPI Validator handler should be called before an actual API is called.\nThe configuration shown above shows the default settings.\nThe `filepath` configuration is required; without it, or when pointing to a non-existing file, the module won't be loaded.\n\n## Example\n\nAn example of the OpenAPI Validatory HTTP handler in use can be found [here](https://github.com/hslatman/caddy-openapi-validator-example).\n\n## Notes\n\nThis project is currently a small POC with the intention to grow it along with my other projects using Go, OpenAPI and Caddy.\nI only recently started using Caddy, so there may be some rough edges to iron out when more use cases present themselves.\n\n## TODO\n\nA small and incomplete list of potential things to implement, improve and think about:\n\n* Add more tests for the OpenAPI Validator functionality and configuration.\n* Improve Caddyfile handling (e.g. add more subdirectives).\n* Add an example that uses an HTTP proxy/fcgi configuration.\n* Look into ways to specify the error nicely, instead of just logging it (e.g. return error message(s) in specific format) and/or integrate properly with how Caddy handlers errors.\n* Look into if (and how) the Validator can be used outside of Caddy as an alternative (i.e. a more generic middleware).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhslatman%2Fcaddy-openapi-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhslatman%2Fcaddy-openapi-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhslatman%2Fcaddy-openapi-validator/lists"}