{"id":19315237,"url":"https://github.com/jamalzeynalov/swagger-coverage-py","last_synced_at":"2025-08-01T17:37:25.326Z","repository":{"id":45866929,"uuid":"334348350","full_name":"JamalZeynalov/swagger-coverage-py","owner":"JamalZeynalov","description":"Adaptation of swagger-coverage project for python","archived":false,"fork":false,"pushed_at":"2024-06-10T14:49:29.000Z","size":33897,"stargazers_count":34,"open_issues_count":1,"forks_count":30,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-21T01:26:02.911Z","etag":null,"topics":["api-testing","api-testing-framework","coverage-report","coverage-reports","coverage-testing","openapi","pytest","requests","swagger","swagger-coverage"],"latest_commit_sha":null,"homepage":"","language":"Python","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/JamalZeynalov.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,"zenodo":null}},"created_at":"2021-01-30T06:49:55.000Z","updated_at":"2025-05-03T10:43:14.000Z","dependencies_parsed_at":"2024-06-20T19:00:51.460Z","dependency_job_id":"31524481-c1ec-4b93-bd16-37f21f615f79","html_url":"https://github.com/JamalZeynalov/swagger-coverage-py","commit_stats":{"total_commits":65,"total_committers":4,"mean_commits":16.25,"dds":0.3384615384615385,"last_synced_commit":"fe1f4beb2d8b0e4e4a99f12d7e15b7764768bc32"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/JamalZeynalov/swagger-coverage-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamalZeynalov%2Fswagger-coverage-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamalZeynalov%2Fswagger-coverage-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamalZeynalov%2Fswagger-coverage-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamalZeynalov%2Fswagger-coverage-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JamalZeynalov","download_url":"https://codeload.github.com/JamalZeynalov/swagger-coverage-py/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamalZeynalov%2Fswagger-coverage-py/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268268687,"owners_count":24223106,"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-08-01T02:00:08.611Z","response_time":67,"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":["api-testing","api-testing-framework","coverage-report","coverage-reports","coverage-testing","openapi","pytest","requests","swagger","swagger-coverage"],"created_at":"2024-11-10T01:05:25.848Z","updated_at":"2025-08-01T17:37:25.300Z","avatar_url":"https://github.com/JamalZeynalov.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Supported Python Versions](https://img.shields.io/badge/python-3.6-blue)\n![Version](https://img.shields.io/badge/Version-2.0.1-blue)\n\n# swagger-coverage-py\n\n#### This project is the adapter that allows using [swagger-coverage](https://github.com/viclovsky/swagger-coverage) tool in Python projects (PyTest+Requests).\n\n## Original description summary:\n\n\u003e Swagger-coverage gives a full picture about coverage of API tests (regression) based on OAS 2 (Swagger). By saying\n\u003e coverage we mean not a broad theme functionality, but presence (or absence) of calls defined by API methods, parameters,\n\u003e return codes or other conditions which corresponds specification of API.\n\nSome more info about the project you can also\nfind [HERE](https://viclovsky.github.io/%D0%B0%D0%B2%D1%82%D0%BE%D1%82%D0%B5%D1%81%D1%82%D1%8B%20%D0%BD%D0%B0%20api/2020/01/16/swagger-coverage)\n\u003cbr\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/JamalZeynalov/swagger-coverage-py/master/images/swagger-coverage-report.png\" width=1100\u003e\n\n# How to use:\n\nAll required steps are listed below. Additionally, you can find a working example\nhere: [allure-results-sample](https://github.com/JamalZeynalov/allure-results-sample).\n\n### 0. Resolve dependencies:\n\n* python 3.6+\n* java JDK 11+ (with JAVA_HOME environment variable set)\n* Enable Long Paths (Windows only). Check the\n  guide [HERE](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation#enable-long-paths-in-windows-10-version-1607-and-later)\n\n### 1. Install `swagger-coverage-py` as a project requirement.\n\n```shell\npip install swagger-coverage\n```\n\n### 2. Add environment variables (Optionally):\n\n```dotenv\nAPI_DOCS_TYPE=\"swagger\"  # Note: \"openapi\" is default type of API docs\nAPI_DOCS_VERSION=\"2.0\"  # Note: \"3.0.0\" is default version of API docs\nAPI_DOCS_FORMAT=\"yaml\"  # Note: \"json\" is default format of API docs and output files\nAPI_COVERAGE_REPORTS_DISABLED=True  # Skip requests recording. No files will be saved to 'swagger-coverage-output' dir \nDEBUG_MODE=True  # Enable debug mode. All commandline logs will be printed to console (False by default)\n\n```\n\n### 3. Add the session-scoped fixture\n\n```python\nimport pytest\nfrom swagger_coverage_py.reporter import CoverageReporter\nfrom requests.auth import HTTPBasicAuth\n\n\n@pytest.fixture(scope=\"session\", autouse=True)\ndef setup_swagger_coverage():\n    reporter = CoverageReporter(api_name=\"my-project\", host=\"http://my-project.com\")\n    reporter.cleanup_input_files()\n    reporter.setup(\"/api/v1/resources/my_project/doc/swagger.json\", auth=HTTPBasicAuth(\"username\", \"password\"))\n\n    yield\n    reporter.generate_report()\n```\n\n#### If you have 2 and more projects, then just add more reporters:\n\n```python\nimport pytest\nfrom swagger_coverage_py.reporter import CoverageReporter\nfrom requests.auth import HTTPBasicAuth\n\n\n@pytest.fixture(scope=\"session\", autouse=True)\ndef setup_swagger_coverage():\n    reporter = CoverageReporter(api_name=\"petstore\", host=\"https://petstore.swagger.io\")\n    reporter.cleanup_input_files()\n    reporter.setup(path_to_swagger_json=\"/v2/swagger.json\")\n\n    reporter2 = CoverageReporter(api_name=\"my-project\", host=\"http://my-project.com\")\n    reporter2.cleanup_input_files()\n    reporter2.setup(path_to_swagger_json=\"/api/v1/swagger.json\", auth=HTTPBasicAuth(\"username\", \"password\"))\n\n    yield\n    reporter.generate_report()\n    reporter2.generate_report()\n```\n\n#### YAML format is also supported:\n\n```python\nimport pytest\nfrom swagger_coverage_py.reporter import CoverageReporter\n\n\n@pytest.fixture(scope=\"session\", autouse=True)\ndef setup_swagger_coverage():\n    reporter = CoverageReporter(api_name=\"petstore\", host=\"https://petstore.swagger.io\")\n    reporter.cleanup_input_files()\n    reporter.setup(\"/v2/swagger.yaml\")\n\n    yield\n    reporter.generate_report()\n```\n\n\u003e #### Steps and Parameters:\n\u003e `api_name` - Define the name of the API. This name will be used to find a configuration file.\u003cbr\u003e\n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; For APIs in this example the files must\n\u003e have names `swagger-coverage-config-petstore.json` and `swagger-coverage-config-my-project.json`.\u003cbr\u003e\n\u003e\n\u003e `host` - The host of the API.\n\u003e It will be used to download a swagger.json file and to identify the CoverageListener output directory for each API.\n\u003e\n\u003e `cleanup_input_files()` - THis step deletes all files in the CoverageListener output directory (according to the\n\u003e target host)\n\u003e\n\u003e `path_to_swagger_json` - A second part of the HTTP link to your OpenApi/Swagger documentation in JSON format\u003cbr\u003e\n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; Adapted `swagger-\u003capi_name\u003e.json` file will be created in your project root.\u003cbr\u003e\n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; The \"Swagger 2.0\" format is completely compatible with this tool.\u003cbr\u003e\n\u003e \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; The \"OpenAPI 3.0.2\" format is partly compatible.\n\u003e \"Tags coverage summary\" calculation is not supported.\u003cbr\u003e\n\u003e\n\u003e `auth` - An authentication parameter for \"requests\" lib. Skip it if your API doesn't require authentication.\n\n### 4. Create and place `swagger-coverage-config-\u003capi_name\u003e.json` file(s) to your project:\n\n```json\n{\n    \"rules\": {\n        \"status\": {\n            \"enable\": true,\n            \"ignore\": [\n                \"500\"\n            ],\n            \"filter\": []\n        },\n        \"paths\": {\n            \"enable\": true,\n            \"ignore\": [\n                \"/user/{username}\"\n            ]\n        },\n        \"only-declared-status\": {\n            \"enable\": false\n        },\n        \"exclude-deprecated\": {\n            \"enable\": true\n        }\n    },\n    \"writers\": {\n        \"html\": {\n            \"locale\": \"en\",\n            \"filename\": \"swagger-coverage-report-petstore.html\"\n        }\n    }\n}\n```\nThe `path` section is designed to exclude specific endpoints (all methods) from the final HTML report.\nTo do this, you need to set `enable` parameter to `true` and specify a list of endpoints (as you see them in the swagger doc) in the `ignore` section. \nThen these endpoints will be removed from the API doc before it is saved locally.\u003cbr\u003e\nNote: Remove already downloaded API docs before running a new version of this lib.\n\n\u003e ### If you have more than 1 API then this config MUST:\n\u003e #### 1. Be created for each microservice which you track using `CoverageListener`.\n\u003e Otherwise, the default behavior will be applied, and your report will be saved as `swagger-coverage-report.html` which\n\u003e may cause override in case you have multiple APIs\n\u003e #### 2. Contain `writers` section with filename in the format: `swagger-coverage-report-\u003capi_name\u003e.html`\n\u003e #### 3. Be placed in the root of your project\n\nMore examples of configuration options you can find in\nthe [Configuration options](https://github.com/JamalZeynalov/swagger-coverage#configuration-options) section of the\ndocumentation.\n\n### 5. Trace all your API calls with CoverageListener:\n\n```python\nfrom requests import Response\nfrom requests.auth import HTTPBasicAuth\nfrom swagger_coverage_py.listener import CoverageListener\n\nresponse: Response = CoverageListener(\n    method=\"get\",\n    base_url=\"https://petstore.swagger.io\",\n    raw_path=\"/v2/store/order/{orderId}\",\n    uri_params={\"orderId\": 1},\n    auth=HTTPBasicAuth(\"username\", \"password\"),\n    params={\"type\": \"active\"},\n).response\n```\n\n\u003e #### Note: \"auth\" and \"params\" arguments are default for \"requests\" lib and are not required. \u003cbr\u003eYou can use any other **kwargs that are applicable for Requests library.\n\n### 6. Run your tests and open created `swagger-coverage-report-\u003capi_name\u003e.html` report(s) in your browser.\n\nImportant remarks:\n\n1. Virtual environments are supported. Make sure your virtual environment directory has name `venv`.\n2. To create report you have to run your test from the project root. Check that workind directory of your runner is\n   not `\"\u003croot\u003e/test\"`\n\n# How it works:\n\n1. The fixture `setup_swagger_coverage` setups required artifacts\n2. During test execution the CoverageListener saves all requests as JSON files in swagger format to a subdirectory named\n   as a called host. (e.g. `swagger-coverage-output/petstore.swagger.io/`).\n3. After all tests execution a `CoverageReporter().generate_report()` creates and saves new report(s) into your project\n   root.\n\n## Created \u0026 Maintained By\n\n[Jamal Zeinalov](https://github.com/JamalZeynalov)\n\n## License\n\nSwagger coverage is released under version 2.0 of the [Apache License](http://www.apache.org/licenses/LICENSE-2.0)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamalzeynalov%2Fswagger-coverage-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamalzeynalov%2Fswagger-coverage-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamalzeynalov%2Fswagger-coverage-py/lists"}