{"id":18291180,"url":"https://github.com/rhecosystemappeng/go-openapi-spec-code-diffs","last_synced_at":"2025-10-10T18:34:09.302Z","repository":{"id":181005583,"uuid":"666011427","full_name":"RHEcosystemAppEng/go-openapi-spec-code-diffs","owner":"RHEcosystemAppEng","description":null,"archived":false,"fork":false,"pushed_at":"2023-07-25T14:58:01.000Z","size":5228,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T07:49:33.897Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/RHEcosystemAppEng.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}},"created_at":"2023-07-13T13:55:40.000Z","updated_at":"2025-03-27T00:26:45.000Z","dependencies_parsed_at":"2023-09-05T03:15:08.179Z","dependency_job_id":null,"html_url":"https://github.com/RHEcosystemAppEng/go-openapi-spec-code-diffs","commit_stats":null,"previous_names":["rhecosystemappeng/openapi-spec-code-diffs","rhecosystemappeng/go-openapi-spec-code-diffs","rhecosystemappeng/openapi_spec_code_diffs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/RHEcosystemAppEng/go-openapi-spec-code-diffs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RHEcosystemAppEng%2Fgo-openapi-spec-code-diffs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RHEcosystemAppEng%2Fgo-openapi-spec-code-diffs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RHEcosystemAppEng%2Fgo-openapi-spec-code-diffs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RHEcosystemAppEng%2Fgo-openapi-spec-code-diffs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RHEcosystemAppEng","download_url":"https://codeload.github.com/RHEcosystemAppEng/go-openapi-spec-code-diffs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RHEcosystemAppEng%2Fgo-openapi-spec-code-diffs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004909,"owners_count":26083803,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-05T14:13:26.105Z","updated_at":"2025-10-10T18:34:09.286Z","avatar_url":"https://github.com/RHEcosystemAppEng.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAPI Specs Validator\n\n## Summary\nA validation tool that compares OpenAPI specs vis-a-vis routes (e.g. /api/v1/customer/:id) defined in golang source code. Useful in scenarios where you want to ensure the OpenAPI specs and Code are in synch.\n\n## What\nThis validator validates API Endpoints defined in golang source code with OpenAPI specifications and reports following differences.\n* OpenAPI specs found in specifications but not found in golang source code\n* Routes found in golang source code but not found in OpenAPI specs.\n\n## Why\n* Helps to keep OpenAPI specs and golang source code in synch.\n* Do not forget to implement paths defined in OpenAPI specs in golang source code.\n* Do not forget to include APIs implemented in golang source code in OpenAPI specs in.\n\n## How\n* This tool takes golang source root directory which implements your API and OpenAPI specs file as inputs.\n* The tool essentially builds two lists: \n  1. List of routes/paths found in golang source code.\n  2. List of routes/paths defined in your OpenAPI specs file.\n  * Both the lists should match if not the tool will report differences.\n* The tool uses regular expressions to find paths defined in golang source code e.g. \"/health/ready\", \"/users\" etc.\n  * Once such a path is found, the corresponding line is scanned to look for a httpmethod such as GET, PUT, POST, DELETE, HEAD, OPTIONS and PATCH.\n  * If the httpmethod is found on the line then tool considers the path found in the line as a valid route/path definition.\n  * Thus following code is considered a valid route/path definition by the tool.\n```go\nroute := routeRegistration{\"PUT\", \"/user/:id/admin/:isAdmin\", handlers.SetAdminStatus}\n```\n  * However the following line is not considered a valid route/path definition as this is the line having a golang keyword 'if'.\n```go\nif \"/this/is/not/considered/a/path/definition\" == \"DELETE\" {\n```\n  * You can make use of the following ignore elements while scanning golang source code, to further fine tune the run of the tool. \n\n| Element       | Description |\n|------------------|-------------|\n| ignoredDirsFile  | Directories to be ignored when scanning golang source code |\n| ignoredFilesFile | Files to be ignored |\n| ignoredLinesFile | Lines to be ignored |\n| ignoredPathsFile | API Paths to be ignored from comparison such as /health/ready or /health/live |\n\n## Why the ignored elements above are needed?\n* The tool recursively works on .go files found in golang source code directory.\n* You can slightly improve the performance by specifying directories which typically do not contain .go files such as bin, out and .git e.g.\n* You can use ignoredFilesFile to further exclude specific files from scanning.\n* If the ignored directories and files are not sufficient, if tool confuses certain code lines to contain valid paths/routes but if they are not valid paths/routes, simply copy those line in ignoredLinesFile and those lines will be ignored from scan.\n\n## Usage\n### As shell command\n* The command line version makes use of named arguments. \n* At any point to see the help for the command use the following\n```shell\nopenapi_spec_code_diffs --help\n```\n* Format\n```shell\nopenapi_spec_code_diffs /\n    -openAPISpecsFile 'path/to/openapi/specs/filename' /\n    -goSourceDir 'path/to/golang/source/dir' /\n    -ignoredDirsFile 'path/to/ignored/directories/filename' / \n    -ignoredFilesFile 'path/to/ignored/files/filename' /\n    -ignoredLinesFile 'path/to/ignored/lines/filename' / \n    -ignoredPathsFile 'path/to/ignored/paths/filename' / \n    -logLevel 'log-level can be one of: disabled, info, debug, error'\n```\n\n### As a package/library in golang source code\n* Import the package/library\n```go\nimport \"github.com/RHEcosystemAppEng/openapi_spec_code_diffs/validator\"\n```\n\n* Use the validator e.g. in test code as follows. Paths below are relative to the path of the test file from which tests are going to be executed from.\n```go\nfunc validateOpenAPISpecs(t *testing.T) {\n\toasStaticValidator := validator.NewOpenAPISpecCodeDiffsValidator(\"./oasStaticValidator/.dirignore\", \"./oasStaticValidator/.specignore\", \"../../\", \"../../openapi.yaml\")\n\terr, result := oasStaticValidator.Validate()\n\n\tassert.Nil(t, err, \"No errors returned from openapi validation\")\n\tassert.Equal(t, 0, len(result.SpecDefsNotInCode), \"Found spec defs not implemented in code\", len(result.SpecDefsNotInCode))\n\tassert.Equal(t, 0, len(result.CodeDefsNotSpec), \"Found code defs not reflected in specs\", len(result.CodeDefsNotSpec))\n}\n```\n\n## Running tests\n* Use the standard go command to run tests as follows, which are divided as positive and negative tests:\n```shell\n go test -v ./tests/positive ./tests/negative\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhecosystemappeng%2Fgo-openapi-spec-code-diffs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhecosystemappeng%2Fgo-openapi-spec-code-diffs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhecosystemappeng%2Fgo-openapi-spec-code-diffs/lists"}