{"id":15091491,"url":"https://github.com/viclovsky/swagger-coverage","last_synced_at":"2025-10-23T17:03:37.475Z","repository":{"id":39885763,"uuid":"218541306","full_name":"viclovsky/swagger-coverage","owner":"viclovsky","description":"Tool which generates full picture of coverage of API tests based on OAS (Swagger) v2 and v3","archived":false,"fork":false,"pushed_at":"2024-01-17T12:13:41.000Z","size":3129,"stargazers_count":203,"open_issues_count":32,"forks_count":42,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-29T16:05:52.980Z","etag":null,"topics":["coverage","oas","swagger"],"latest_commit_sha":null,"homepage":"","language":"Java","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/viclovsky.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-30T14:04:24.000Z","updated_at":"2025-03-19T11:22:06.000Z","dependencies_parsed_at":"2024-09-25T10:41:34.864Z","dependency_job_id":"5a9dafdf-3e04-4f26-871a-39732735c223","html_url":"https://github.com/viclovsky/swagger-coverage","commit_stats":{"total_commits":236,"total_committers":18,"mean_commits":13.11111111111111,"dds":"0.39406779661016944","last_synced_commit":"3d420920ce25d8056ffbd6725e3bbc18483b98e6"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viclovsky%2Fswagger-coverage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viclovsky%2Fswagger-coverage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viclovsky%2Fswagger-coverage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viclovsky%2Fswagger-coverage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/viclovsky","download_url":"https://codeload.github.com/viclovsky/swagger-coverage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369952,"owners_count":20927928,"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":["coverage","oas","swagger"],"created_at":"2024-09-25T10:41:23.362Z","updated_at":"2025-10-23T17:03:32.450Z","avatar_url":"https://github.com/viclovsky.png","language":"Java","readme":"[license]: http://www.apache.org/licenses/LICENSE-2.0 \"Apache License 2.0\"\n[release]: https://github.com/viclovsky/swagger-coverage/releases/latest \"Latest release\"\n[release-badge]: https://img.shields.io/github/release/viclovsky/swagger-coverage.svg?style=flat\n[maven]: https://repo.maven.apache.org/maven2/com/github/viclovsky/swagger-coverage-commandline/ \"Maven Central\"\n[maven-badge]: https://img.shields.io/maven-central/v/com.github.viclovsky/swagger-coverage-commandline.svg?style=flat\n\n[![Build Status](https://github.com/viclovsky/swagger-coverage/workflows/Build/badge.svg)](https://github.com/viclovsky/swagger-coverage/actions)\n[![release-badge][]][release]\n[![maven-badge][]][maven] \n\n# swagger-coverage\nSwagger-coverage gives a full picture about coverage of API tests (regression) based on OAS (Swagger). \nBy saying coverage we mean not a broad theme functionality, but presence (or absence) of calls defined by API methods, parameters, return codes or other conditions which corresponds specification of API.\n\n![Swagger Coverage Report](.github/swagger-coverage.png)\n\n## How it works\nProducing coverage report consists of two parts. Firstly, during test execution, filter/interceptor/proxy save information of calls in swagger format in specific folder on executing tests.\nThe next stage is to compare saved result with generated conditions from current API specification and builds report.  \n\n## How to use and examples\nYou can use swagger-coverage with any language and framework. You need to have proxy/filter/interceptor that accumulates data in swagger format. \nSwagger-coverage have rest-assured integration from the box.\n\n\u003e There is also a Karate integration, which has its own [manual](/swagger-coverage-karate/README.md).\n\nAdd filter dependency:\n```xml\n \u003cdependency\u003e\n     \u003cgroupId\u003ecom.github.viclovsky\u003c/groupId\u003e\n     \u003cartifactId\u003eswagger-coverage-rest-assured\u003c/artifactId\u003e\n     \u003cversion\u003e${latest-swagger-coverage-version}\u003c/version\u003e\n \u003c/dependency\u003e\n```\nor if use gradle, it can be added like\n\n```\ncompile \"com.github.viclovsky:swagger-coverage-rest-assured:$latest-swagger-coverage-version\"\n```\n\nJust add filter into test client SwaggerCoverageRestAssured (SwaggerCoverageV3RestAssured for v3). For instance, as presented below:\n```java\nRestAssured.given().filter(new SwaggerCoverageRestAssured())\n```\n\n* Download and run command line.\nDownload zip archive and unpack it. Don't forget to replace {latest-swagger-coverage-version} to latest version. \n```\nwget https://github.com/viclovsky/swagger-coverage/releases/download/{latest-swagger-coverage-version}/swagger-coverage-{latest-swagger-coverage-version}.zip\nunzip swagger-coverage-commandline-{latest-swagger-coverage-version}.zip\n```\n\nHere is help of unzip swagger-commandline\n\n```\n./swagger-coverage-commandline --help\n\n  Options:\n  * -s, --spec\n      Path to local or URL to remote swagger specification.\n  * -i, --input\n      Path to folder with generated files with coverage.\n    -c, --configuration\n      Path to file with report configuration.\n    --help\n      Print commandline help.\n    -q, --quiet\n      Switch on the quiet mode.\n      Default: false\n    -v, --verbose\n      Switch on the verbose mode.\n      Default: false\n```\n\nTo compare result of API tests with current API specification and build report call command line tool after running tests like that:\n\n```\n./swagger-coverage-commandline -s swagger.json -i swagger-coverage-output\n```\n\nOutput of the command:\n```\n19:21:21 INFO  OperationSwaggerCoverageCalculator - Empty coverage:\n...\n19:21:21 INFO  OperationSwaggerCoverageCalculator - Partial coverage:\n...\n19:21:21 INFO  OperationSwaggerCoverageCalculator - Full coverage:\n...\n19:21:21 INFO  OperationSwaggerCoverageCalculator - Conditions: 874/2520\n19:21:21 INFO  OperationSwaggerCoverageCalculator - Empty coverage 49.284 %\n19:21:21 INFO  OperationSwaggerCoverageCalculator - Partial coverage 12.034 %\n19:21:21 INFO  OperationSwaggerCoverageCalculator - Full coverage 38.682 %\n19:21:21 INFO  FileSystemResultsWriter - Write html report in file '.../swagger-coverage-report.html'\n```\nResults (swagger-coverage-report.html/swagger-coverage-results.json) will be created after running of swagger-coverage.\n\n## Configuration options\nSwagger-coverage report can be configured by json-file. \nYou can control list of coverage, which be generated and checked for results.\n\n## Rules configuration options\nOptions for different rules are placed in \"rules\" section. \nYou can disable some rules or change their behavior.\n\n#### Checking response http-status\nThis rule create condition for every status from *responses*-section of swagger specification.\nCondition mark *covered* when report generator find specific status in results files.\nOptions for this rules are placed in *status* subsection in *rules* sections.\n\nYou can setup next options:\n\n**enable** - *true/false*. You can disable this rule. Default value is *true*.\n\n**filter** - *[val1,val2]*. Rule will ignore all status, which not in filter list.\n\n**ignore** - *[val1,val2]*. Rule will ignore all status, which in ignore list.\n\n```` \n{\n  \"rules\" : {\n    \"status\": {\n      \"enable\": true,\n      \"ignore\": [\"400\",\"500\"],\n      \"filter\": [\"200\"]\n    },\n\n    ....\n  },\n  \n  ....\n}\n````\n\n#### Checking the list of declared and received statuses\nThis rule create condition for comparing declared and received status. \nCondition marked as *covered* when result not contains any of undeclared status.\n*Uncovered* state of this condition indicates missed status in original swagger-documentation \nor server errors.\nOptions for this rules are placed in *only-declared-status* subsection in *rules* sections.\n\n\nYou can setup next options:\n\n**enable** - *true/false*. You can disable this rule. Default value is *true*.\n\n````\n{\n  \"rules\" : {\n\n    ....\n\n    \"only-declared-status\" : {\n      \"enable\" : true\n    }\n  },\n\n   ....\n}\n````\n\n#### Excluding deprecated operations from the coverage report statistic\nThis rule is created for cases when you don't want to measure coverage of deprecated operations, but only for actual ones. \u003cbr\u003e\nIf an operation is deprecated then it will be excluded from *Full*, *Partial*, and *Empty* categories and won't affect the \"Operations coverage summary\"\n\nOptions for this rule are placed in \"*exclude-deprecated*\" subsection in *rules* sections.\n\nYou can set up next options:\n\n**enable** - *true/false*. \u003cbr\u003e\nBy default, this rule is not enabled. Add it to the config file with *true* value to enable this rule, like in the example below:\n\n````\n{\n  \"rules\" : {\n\n    ....\n\n    \"exclude-deprecated\" : {\n      \"enable\" : true\n    }\n  },\n\n   ....\n}\n````\n\nIf you need you can add your rules for generation of conditions. So, please, send your PRs.\n\n## Result writer configuration\nOptions for report generation setting are placed in *writers* sections.\n\n#### HTML report writer\nOptions for html-report placed in subsection *html* of *writers* sections.\n\nYou can setup next options:\n\n**locale** - two latter language code. Now supported only *en/ru*.\n\n**filename** - filename for html report.\n\n**numberFormat** - [Extended Java decimal format](https://freemarker.apache.org/docs/ref_builtins_number.html#topic.extendedJavaDecimalFormat) to control how numbers are displayed in the report.\n\n````\n{\n  ....\n\n  \"writers\": {\n      \"html\": {\n        \"locale\": \"ru\",\n        \"filename\":\"report.html\",\n        \"numberFormat\": \"0.##\"\n      }\n  }\n}\n````\n\n#### Report customization\nTo customize your http report with your own template set full path to the template like below:\n````\n{\n  ....\n  \n  \"writers\": {\n    \"html\": {\n      ....\n      \"customTemplatePath\": \"/full/path/to/report_custom.ftl\"\n    }\n  }\n}\n````\n\n[Look here](https://github.com/swagger-api/swagger-parser/blob/master/modules/swagger-parser-core/src/main/java/io/swagger/v3/parser/core/models/ParseOptions.java) to see all available options.\n\n\n## Demo\nI have prepared several tests. Thus you are able to have a look and touch swagger-coverage. Just run ```run.sh``` script.\n\n## Important remark\nSwagger-coverage works fine with clients which were generated from swagger (for example: https://github.com/OpenAPITools/openapi-generator). \nBecause all methods/parameters which will be saved are 100% compatible with current API specification. \n\n## Requirements \n\nFor a moment swagger-coverage  is compatible only with OpenApi specifications v2 \u0026 v3. It is possible that swagger-coverage will support other versions.\n\n## Pull Requests\nMy project is open for any enhancement. So, your help is much appreciated. Please, feel free to open your pull request or issue and I will consider it in several days.\n\n## Created \u0026 Maintained By\n[Victor Orlovsky](https://github.com/viclovsky)\n\n## Contributing to swagger-coverage\nThanks to all people who contributed. Especially \n\n* [@TemaMak](https://github.com/TemaMak) \n* [@Emilio-Pega](https://github.com/Emilio-Pega)\n\nwho have contributed significant improvements to swagger-coverage.\n\n## License\nSwagger coverage is released under version 2.0 of the [Apache License](http://www.apache.org/licenses/LICENSE-2.0)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviclovsky%2Fswagger-coverage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fviclovsky%2Fswagger-coverage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviclovsky%2Fswagger-coverage/lists"}