{"id":29995119,"url":"https://github.com/mike-brady/flask-apispec-tools","last_synced_at":"2026-04-29T16:38:26.151Z","repository":{"id":216152604,"uuid":"617754461","full_name":"mike-brady/flask-apispec-tools","owner":"mike-brady","description":null,"archived":false,"fork":false,"pushed_at":"2023-03-30T01:16:35.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-02T08:44:21.382Z","etag":null,"topics":["apispec","flask","openapi","python","swagger-ui"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/flask-apispec-tools/","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/mike-brady.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-03-23T03:11:58.000Z","updated_at":"2023-03-30T01:31:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"96ba73ed-6a0c-4cad-b098-7ff9528fe3b7","html_url":"https://github.com/mike-brady/flask-apispec-tools","commit_stats":null,"previous_names":["mike-brady/flask-apispec-tools"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mike-brady/flask-apispec-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mike-brady%2Fflask-apispec-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mike-brady%2Fflask-apispec-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mike-brady%2Fflask-apispec-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mike-brady%2Fflask-apispec-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mike-brady","download_url":"https://codeload.github.com/mike-brady/flask-apispec-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mike-brady%2Fflask-apispec-tools/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268815427,"owners_count":24311567,"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-04T02:00:09.867Z","response_time":79,"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":["apispec","flask","openapi","python","swagger-ui"],"created_at":"2025-08-05T01:04:28.710Z","updated_at":"2026-04-29T16:38:26.082Z","avatar_url":"https://github.com/mike-brady.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nA set of tools to aid in adding [APISpec](https://apispec.readthedocs.io/en/latest/) to [Flask](https://palletsprojects.com/p/flask) projects.\n\n\n## Installation\n\n```\npip install flask-apispec-tools\n```\n\n## Configuration\nflask-apispec-tools requires the following inside the Flask app config.\n```\n[FLASK_APISPEC_TOOLS]\nversion =\ntitle =\ndescription =\ndocs_dir =\ndocs_type =\n```\n|             |                                                                           |\n|-------------|---------------------------------------------------------------------------|\n| version     | The version of your api.                                                  |\n| title       | The name of your api.                                                     |\n| description | A description of your api.                                                |\n| docs_dir    | The directory where api docs are to be stored.                            |\n| docs_type   | The format you want your docs created as. Can be either \"json\" or \"yaml\". |\n\n### Setting Config Values\nThere are multiple ways to add the config items to the Flask app. See [Flask Configuration Handling](https://flask.palletsprojects.com/en/2.2.x/config/). While it is recommended to use separate config files or environment variables, flask-apispec-tools allows you to pass configuration values to the `init()` function. See [Configuring flask-apispec-tools with init()](#configuring-flask-apispec-tools-with-init).\n\n### Referencing Other Config Options\nConfig values can be references to other config options using the format `${section:option}`.\n```\n[FLASK_APISPEC_TOOLS]\nversion = ${METADATA:version}\ntitle = ${METADATA:title}\ndescription = ${METADATA:description}\ndocs_dir = myproj/static/docs\ndocs_type = json\n```\n## Initialization\n```flask_apispec_tools.init(app)```\n\nThis registers the cli command `generate-api-docs` with Flask and adds 3 endpoints ( `/docs`, `/docs/json` or `/docs/yaml`, `/version`) to the app.\n\n### Customizing Built-in Endpoints\nAdding these endpoints can be disabled or their paths can be changed by passing additional arguments to `init()`.\n\nThe example below sets the paths for the docs and docs_json endpoints and disables the version endpoint.\n\n```\nflask_apispec_tools.init(\n    app,\n    docs_endpoint='/api/docs',\n    docs_json_endpoint='/api/docs/json',\n    version_endpoint=False\n)\n```\n### APISpec Plugins\nA list of apispec plugins can be passed to `init()` and they will be given to the APISpec object. See [APISpec Using Plugins](https://apispec.readthedocs.io/en/latest/using_plugins.html). You do not need to give `init()` the FlaskPlugin.\n```\nflask_apispec_tools.init(\n    app,\n    plugins=[MarshmallowPlugin(), MyCustomPlugin()]\n)\n```\n### Configuring flask-apispec-tools with init()\nflask-apispec-tools can be configured by passing a dictionary of config values to `init()`. This will override any existing configuration values.\n```\nflask_apispec_tools.init(\n    app,\n    config_values={\n        'docs_dir': '/docs',\n        'docs_type': 'json'\n    }\n)\n```\n## Generating API Docs\n`flask generate-api-docs`\n\n### Options\n`-a, --all Include enpoints marked 'Exclude From Spec'.`\n\n## Excluding Endpoints\nEndpoints can be excluded from docs by adding `Exclude From Spec` at the top of the docstring. This exclusion can be ignored using `-a` or `--all` with `flask generate-api-docs`.\n```\nclass MyEndpoint(MethodView):\n    \"\"\"Exclude From Spec\"\"\"\n\n    def get(self):\n        ...\n```\n\n## Validating Your API\nflask-apispec-tools provides a function that you can register with a [Flask Test Client](https://flask.palletsprojects.com/en/2.2.x/testing/#sending-requests-with-the-test-client) to run [after each request](https://flask.palletsprojects.com/en/2.2.x/api/#flask.Blueprint.after_request) sent during tests. The validator inspects both the [Request](https://flask.palletsprojects.com/en/2.2.x/api/?#flask.Request) and [Response](https://flask.palletsprojects.com/en/2.2.x/api/?#flask.Response) objects and compares them to the API specification. If the validation fails an [APISpecError](https://apispec.readthedocs.io/en/latest/api_core.html#apispec.exceptions.APISpecError) is raised, and the test will fail.\n\n### Setup\n ```\n from flask_apispec_tools.testing import response_validator\n\n\t...\n\tapp.after_request(response_validator())\n\t...\n ```\n### Example Failed Test\n```\n==================================== short test summary info ====================================\nFAILED tests.py::test_docs - apispec.exceptions.APISpecError: GET /docs -\u003e 200: text/html missing\n================================== 1 failed, 41 passed in 0.49s =================================\n```\n\n## Built-in Endpoints\n| endpoint   | description                   | query parameters                                          |\n|------------|-------------------------------|-----------------------------------------------------------|\n| /docs      | Display docs with Swagger UI. | version (optional): Which version of the API docs to get. |\n| /docs/json | Get docs as JSON.             | version (optional): Which version of the API docs to get. |\n| /docs/yaml | Get docs as YAML.             | version (optional): Which version of the API docs to get. |\n| /version   | Get the API version.          |                                                           |\n\n## Additional Functions\nThese functions are used internally, but you may find them useful as well.\n### `flask_apispec_tools.tools`\n#### config_values(option: str, \\*, config: Config = None) -\u003e str | None:\n```\nGet the value of an option from the config.\n\nArgs:\n\toption: The option to get the value for.\n\tconfig: Optional. Default: flask.current_app.config.\nReturns:\n\tstr: The config value.\n\tNone: The option was not found.\n```\n\n#### get_docs_filename(version: str = None, \\*, config: Config = None) -\u003e str:\n```\nGet the name of a docs file for a specific version.\n\nArgs:\n\tversion: Optional. Default: The version set in the config.\n\tconfig: Optional. Default: flask.current_app.config.\nReturns:\n\t The docs filename.\n```\n\n#### get_docs_filepath(version: str = None, \\*, config: Config = None) -\u003e str:\n```\nGet the filepath of a docs file for a specific version.\n\nArgs:\n\tversion: Optional. Default: The version set in the config.\n\tconfig: Optional. Default: flask.current_app.config.\nReturns:\n\tThe docs filepath.\n ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmike-brady%2Fflask-apispec-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmike-brady%2Fflask-apispec-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmike-brady%2Fflask-apispec-tools/lists"}