{"id":15130924,"url":"https://github.com/kwkwc/flask-docs","last_synced_at":"2025-08-02T18:08:57.675Z","repository":{"id":39174641,"uuid":"134087834","full_name":"kwkwc/flask-docs","owner":"kwkwc","description":"Adds Docs support to Flask","archived":false,"fork":false,"pushed_at":"2024-05-17T14:28:49.000Z","size":1309,"stargazers_count":67,"open_issues_count":0,"forks_count":10,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-20T03:05:31.824Z","etag":null,"topics":["api","debugger","documentation","flask","flask-docs","markdown","python","restful"],"latest_commit_sha":null,"homepage":"https://kwkwc.github.io/flask-docs/","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/kwkwc.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":"2018-05-19T18:25:43.000Z","updated_at":"2024-12-24T02:35:51.000Z","dependencies_parsed_at":"2024-04-14T02:28:07.119Z","dependency_job_id":"af64e6c2-1689-4877-b465-0a0330836967","html_url":"https://github.com/kwkwc/flask-docs","commit_stats":{"total_commits":266,"total_committers":4,"mean_commits":66.5,"dds":"0.045112781954887216","last_synced_commit":"c293b04f57e10189500c10726a6e5fd8fbf8b3ed"},"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"purl":"pkg:github/kwkwc/flask-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwkwc%2Fflask-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwkwc%2Fflask-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwkwc%2Fflask-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwkwc%2Fflask-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kwkwc","download_url":"https://codeload.github.com/kwkwc/flask-docs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kwkwc%2Fflask-docs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268431638,"owners_count":24249413,"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-02T02:00:12.353Z","response_time":74,"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","debugger","documentation","flask","flask-docs","markdown","python","restful"],"created_at":"2024-09-26T03:08:35.196Z","updated_at":"2025-08-02T18:08:57.605Z","avatar_url":"https://github.com/kwkwc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flask-Docs\n\n[![test](https://github.com/kwkwc/flask-docs/actions/workflows/test.yml/badge.svg)](https://github.com/kwkwc/flask-docs/actions/workflows/test.yml)\n[![publish](https://github.com/kwkwc/flask-docs/actions/workflows/publish.yml/badge.svg)](https://github.com/kwkwc/flask-docs/actions/workflows/publish.yml)\n[![codecov](https://codecov.io/gh/kwkwc/flask-docs/branch/master/graph/badge.svg?token=EV69K9WPJ0)](https://codecov.io/gh/kwkwc/flask-docs)\n[![PyPI](https://img.shields.io/pypi/v/Flask-Docs)](https://pypi.org/project/Flask-Docs/)\n[![Python](https://img.shields.io/pypi/pyversions/flask-docs)](https://pypi.org/project/Flask-Docs/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n![GitHub release (with filter)](https://img.shields.io/github/v/release/kwkwc/flask-docs)\n[![license](https://img.shields.io/github/license/kwkwc/flask-docs)](https://github.com/kwkwc/flask-docs/blob/master/LICENSE)\n\n\u003e Adds Docs support to Flask.\n\nEnglish | [简体中文](README.zh-CN.md)\n\n## Features\n\n- Automatic generation of markdown documentation\n- Support offline markdown document download\n- Support Flask-RESTful\n- Support Flask-RESTX\n- Support Flask MethodView\n- Support online debugging\n- Support command to generate offline document\n  - [x] HTML\n  - [x] Markdown\n\n## Installation\n\n```bash\npip3 install Flask-Docs\n```\n\n## Usage\n\n```python\nfrom flask import Flask\nfrom flask_docs import ApiDoc\n\napp = Flask(__name__)\n\n\nApiDoc(\n    app,\n    title=\"Sample App\",\n    version=\"1.0.0\",\n    description=\"A simple app API\",\n)\n```\n\n## View the documentation page\n\n```shell\nhttp://127.0.0.1/docs/api/\n```\n\n## Page demo\n\n[Online Demo][online_demo]\n\n## Configuration\n\n```python\n# Using CDN\n# app.config[\"API_DOC_CDN\"] = True\n\n# Disable document pages\n# app.config[\"API_DOC_ENABLE\"] = False\n\n# SHA256 encrypted authorization password, e.g. here is admin\n# echo -n admin | shasum -a 256\n# app.config[\"API_DOC_PASSWORD_SHA2\"] = \"8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918\"\n\n# Methods allowed to be displayed\n# app.config[\"API_DOC_METHODS_LIST\"] = [\"GET\", \"POST\", \"PUT\", \"DELETE\", \"PATCH\"]\n\n# Custom url_prefix\n# app.config[\"API_DOC_URL_PREFIX\"] = \"/docs/api\"\n\n# RESTful API class name to exclude\n# app.config[\"API_DOC_RESTFUL_EXCLUDE\"] = [\"Todo\"]\n\n# Name of the API blueprint to be displayed\n# app.config[\"API_DOC_MEMBER\"] = [\"api\", \"platform\"]\n\n# Name of the Submembers API function to be excluded\n# app.config[\"API_DOC_MEMBER_SUB_EXCLUDE\"] = [\"delete_data\"]\n\n# Auto generating request args markdown\n# app.config[\"API_DOC_AUTO_GENERATING_ARGS_MD\"] = True\n\n# Disable markdown processing for all documents\n# app.config[\"API_DOC_ALL_MD\"] = False\n```\n\n## Tag @@@\n\n```shell\n# Process all documents in markdown by default\n# 1. use the `@@@` wrapper if you want to specify processing\n# 2. Turn off `API_DOC_ALL_MD` and remove the `@@@` tag if you want to display the original document\n\n@@@\n# Write your markdown document here\n@@@\n```\n\n## API\n\n````python\n@api.route(\"/add_data\", methods=[\"POST\"])\ndef add_data():\n    \"\"\"Add some data\n\n    ### args\n    |  args | required | request type | type |  remarks |\n    |-------|----------|--------------|------|----------|\n    | title |  true    |    body      | str  | blog title    |\n    | name  |  true    |    body      | str  | person's name |\n\n    ### request\n    ```json\n    {\"title\": \"xxx\", \"name\": \"xxx\"}\n    ```\n\n    ### return\n    ```json\n    {\"code\": xxxx, \"msg\": \"xxx\", \"data\": null}\n    ```\n    \"\"\"\n    return jsonify({\"api\": \"add data\"})\n\n\napp.register_blueprint(api, url_prefix=\"/api\")\n````\n\n![sample_app](flask_docs/assets/sample_app_add.png)\n\n````python\n@api.route(\"/delete_data\", methods=[\"GET\"])\ndef delete_data():\n    \"\"\"Delete some data\n\n    @@@\n    ### args\n    |  args  | required | request type | type |  remarks     |\n    |--------|----------|--------------|------|--------------|\n    |  id    |  false   |    query     |  str | blog id    |\n    |  name  |  true    |    query     |  str | person's name |\n\n    ### request\n    ```\n    http://127.0.0.1:5000/api/delete_data?name=xxx\n    ```\n\n    ### return\n    ```json\n    {\"code\": xxxx, \"msg\": \"xxx\", \"data\": null}\n    ```\n    @@@\n    \"\"\"\n\n    return jsonify({\"api\": \"delete data\"})\n\n\napp.register_blueprint(api, url_prefix=\"/api\")\n````\n\n![sample_app](flask_docs/assets/sample_app_delete.png)\n\n````python\n@platform.route(\"/get_something\", methods=[\"GET\"])\ndef get_something():\n    \"\"\"Get some data\n\n    @@@\n    ### request example\n    ```python\n    import requests\n    url=\"http://127.0.0.1:5000/platform/get_something\"\n    try:\n        print(requests.get(url).text)\n    except:\n        pass\n    ```\n\n    ### return\n    ```json\n    {\"code\": xxxx, \"msg\": \"xxx\", \"data\": null}\n    ```\n    @@@\n    \"\"\"\n\n    return jsonify({\"platform\": \"get something\"})\n\n\napp.register_blueprint(platform, url_prefix=\"/platform\")\n````\n\n![sample_app](flask_docs/assets/sample_app_get.png)\n\n## Flask-RESTful API\n\n````python\nfrom flask_restful import Resource, Api\n\nclass Todo(Resource):\n    \"\"\"Manage todo\"\"\"\n\n    def post(self):\n        \"\"\"Add todo\n\n        @@@\n        ### description\n        \u003e Add todo\n\n        ### args\n        |  args | required | request type | type |  remarks |\n        |-------|----------|--------------|------|----------|\n        |  name |  true    |    body      | str  | todo name |\n        |  type |  true    |    body      | str  | todo type |\n\n        ### request\n        ```json\n        {\"name\": \"xx\", \"type\": \"code\"}\n        ```\n\n        ### return\n        ```json\n        {\"code\": xxxx, \"msg\": \"xxx\", \"data\": null}\n        ```\n        @@@\n        \"\"\"\n\n        return {\"todo\": \"post todo\"}\n\n    def get(self):\n        \"\"\"Get todo\n\n        @@@\n        ### description\n        \u003e Get todo\n\n        ### args\n        |  args | required | request type | type |  remarks |\n        |-------|----------|--------------|------|----------|\n        |  name |  true    |    query     | str  | todo name |\n        |  type |  false   |    query     | str  | todo type |\n\n        ### request\n        ```\n        http://127.0.0.1:5000/todo?name=xxx\u0026type=code\n        ```\n\n        ### return\n        ```json\n        {\"code\": xxxx, \"msg\": \"xxx\", \"data\": null}\n        ```\n        @@@\n        \"\"\"\n\n        return {\"todo\": \"get todo\"}\n\n\nrestful_api = Api(app)\nrestful_api.add_resource(Todo, \"/todo\")\n````\n\n![sample_app](flask_docs/assets/sample_app_restful_post.png)\n\n![sample_app](flask_docs/assets/sample_app_restful_get.png)\n\n## Flask MethodView API\n\n\u003e **_For the time being, only url_rule with the same class name are supported_**\n\n```python\nfrom flask.views import MethodView\n\nclass TodoList(MethodView):\n    \"\"\"Manage todolist\"\"\"\n\n    def put(self):\n        \"\"\"Change the data\"\"\"\n\n        return jsonify({\"todos\": \"put todolist\"})\n\n    def delete(self):\n        \"\"\"Delete the data\"\"\"\n\n        return jsonify({\"todos\": \"delete todolist\"})\n\n\napp.add_url_rule(\"/todolist/\", view_func=TodoList.as_view(\"todolist\"))\n```\n\n## Decorator @ApiDoc.change_doc\n\n\u003e Reuse comments\n\n````python\nfrom flask_docs import ApiDoc\n\nreturn_json_str = '{\"code\": xxxx, \"msg\": \"xxx\", \"data\": null}'\n\n@api.route(\"/add_data\", methods=[\"POST\"])\n@ApiDoc.change_doc({\"return_json\": return_json_str})\ndef add_data():\n    \"\"\"Add some data\n\n    @@@\n    ### return\n    ```json\n    return_json\n    ```\n    @@@\n    \"\"\"\n    return jsonify({\"api\": \"add data\"})\n\n\n@api.route(\"/delete_data\", methods=[\"GET\"])\n@ApiDoc.change_doc({\"return_json\": return_json_str})\ndef delete_data():\n    \"\"\"Delete some data\n\n    return_json\n    \"\"\"\n\n    return jsonify({\"api\": \"delete data\"})\n````\n\n## Debugger\n\n![debugger](flask_docs/assets/debugger.png)\n\n## Command to generate offline document\n\n- HTML: Run `flask docs html` will generate offline html document at `htmldoc/`\n- Markdown: Run `flask docs markdown` will generate the `doc.md` offline markdown document\n\n## Examples\n\n[Complete example][examples]\n\n## Thanks\n\n[flask_api_doc](https://github.com/tobyqin/flask_api_doc/)\n\n[Flask-Bootstrap](https://github.com/mbr/flask-bootstrap/)\n\n[github-markdown-css](https://github.com/sindresorhus/github-markdown-css/)\n\n[Bytesize Icons](https://github.com/danklammer/bytesize-icons/)\n\n[RESTClient](https://github.com/chao/RESTClient/)\n\n[examples]: https://github.com/kwkwc/flask-docs/tree/master/examples\n\n[online_demo]: https://kwkwc.github.io/flask-docs-demo/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkwkwc%2Fflask-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkwkwc%2Fflask-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkwkwc%2Fflask-docs/lists"}