# Flask-Docs
[](https://github.com/kwkwc/flask-docs/actions/workflows/test.yml)
[](https://github.com/kwkwc/flask-docs/actions/workflows/publish.yml)
[](https://codecov.io/gh/kwkwc/flask-docs)
[](https://pypi.org/project/Flask-Docs/)
[](https://pypi.org/project/Flask-Docs/)
[](https://github.com/psf/black)
[](https://github.com/kwkwc/flask-docs/blob/master/LICENSE)
> Adds Docs support to Flask.
English | [简体中文](README.zh-CN.md)
## Features
- Automatic generation of markdown documentation
- Support offline markdown document download
- Support Flask-RESTful
- Support Flask-RESTX
- Support Flask MethodView
- Support online debugging
- Support command to generate offline document
- [x] HTML
- [x] Markdown
## Installation
`pip3 install Flask-Docs`
## Usage
```python
from flask import Flask
from flask_docs import ApiDoc
app = Flask(__name__)
ApiDoc(
app,
title="Sample App",
version="1.0.0",
description="A simple app API",
)
```
## View the documentation page
```shell
http://127.0.0.1/docs/api/
```
## Page demo
[Online Demo][online_demo]
## Configuration
```python
# Using CDN
# app.config["API_DOC_CDN"] = True
# Disable document pages
# app.config["API_DOC_ENABLE"] = False
# SHA256 encrypted authorization password, e.g. here is admin
# echo -n admin | shasum -a 256
# app.config["API_DOC_PASSWORD_SHA2"] = "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918"
# Methods allowed to be displayed
# app.config["API_DOC_METHODS_LIST"] = ["GET", "POST", "PUT", "DELETE", "PATCH"]
# Custom url_prefix
# app.config["API_DOC_URL_PREFIX"] = "/docs/api"
# RESTful API class name to exclude
# app.config["API_DOC_RESTFUL_EXCLUDE"] = ["Todo"]
# Name of the API blueprint to be displayed
# app.config["API_DOC_MEMBER"] = ["api", "platform"]
# Name of the Submembers API function to be excluded
# app.config["API_DOC_MEMBER_SUB_EXCLUDE"] = ["delete_data"]
# Auto generating request args markdown
# app.config["API_DOC_AUTO_GENERATING_ARGS_MD"] = True
# Disable markdown processing for all documents
# app.config["API_DOC_ALL_MD"] = False
```
## Tag @@@
```shell
# Process all documents in markdown by default
# 1. use the `@@@` wrapper if you want to specify processing
# 2. Turn off `API_DOC_ALL_MD` and remove the `@@@` tag if you want to display the original document
@@@
# Write your markdown document here
@@@
```
## API
````python
@api.route("/add_data", methods=["POST"])
def add_data():
"""Add some data
### args
| args | required | request type | type | remarks |
|-------|----------|--------------|------|----------|
| title | true | body | str | blog title |
| name | true | body | str | person's name |
### request
```json
{"title": "xxx", "name": "xxx"}
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
"""
return jsonify({"api": "add data"})
app.register_blueprint(api, url_prefix="/api")
````
````python
@api.route("/delete_data", methods=["GET"])
def delete_data():
"""Delete some data
@@@
### args
| args | required | request type | type | remarks |
|--------|----------|--------------|------|--------------|
| id | false | query | str | blog id |
| name | true | query | str | person's name |
### request
```
http://127.0.0.1:5000/api/delete_data?name=xxx
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return jsonify({"api": "delete data"})
app.register_blueprint(api, url_prefix="/api")
````
````python
@platform.route("/get_something", methods=["GET"])
def get_something():
"""Get some data
@@@
### request example
```python
import requests
url="http://127.0.0.1:5000/platform/get_something"
try:
print(requests.get(url).text)
except:
pass
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return jsonify({"platform": "get something"})
app.register_blueprint(platform, url_prefix="/platform")
````
## Flask-RESTful API
````python
from flask_restful import Resource, Api
class Todo(Resource):
"""Manage todo"""
def post(self):
"""Add todo
@@@
### description
> Add todo
### args
| args | required | request type | type | remarks |
|-------|----------|--------------|------|----------|
| name | true | body | str | todo name |
| type | true | body | str | todo type |
### request
```json
{"name": "xx", "type": "code"}
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return {"todo": "post todo"}
def get(self):
"""Get todo
@@@
### description
> Get todo
### args
| args | required | request type | type | remarks |
|-------|----------|--------------|------|----------|
| name | true | query | str | todo name |
| type | false | query | str | todo type |
### request
```
http://127.0.0.1:5000/todo?name=xxx&type=code
```
### return
```json
{"code": xxxx, "msg": "xxx", "data": null}
```
@@@
"""
return {"todo": "get todo"}
restful_api = Api(app)
restful_api.add_resource(Todo, "/todo")
````
## Flask MethodView API
> **_For the time being, only url_rule with the same class name are supported_**
```python
from flask.views import MethodView
class TodoList(MethodView):
"""Manage todolist"""
def put(self):
"""Change the data"""
return jsonify({"todos": "put todolist"})
def delete(self):
"""Delete the data"""
return jsonify({"todos": "delete todolist"})
app.add_url_rule("/todolist/", view_func=TodoList.as_view("todolist"))
```
## Decorator @ApiDoc.change_doc
> Reuse comments
````python
from flask_docs import ApiDoc
return_json_str = '{"code": xxxx, "msg": "xxx", "data": null}'
@api.route("/add_data", methods=["POST"])
@ApiDoc.change_doc({"return_json": return_json_str})
def add_data():
"""Add some data
@@@
### return
```json
return_json
```
@@@
"""
return jsonify({"api": "add data"})
@api.route("/delete_data", methods=["GET"])
@ApiDoc.change_doc({"return_json": return_json_str})
def delete_data():
"""Delete some data
return_json
"""
return jsonify({"api": "delete data"})
````
## Debugger
## Command to generate offline document
- HTML: Run `flask docs html` will generate offline html document at `htmldoc/`
- Markdown: Run `flask docs markdown` will generate the `doc.md` offline markdown document
## Examples
[Complete example][examples]
## Thanks
[flask_api_doc](https://github.com/tobyqin/flask_api_doc/)
[Flask-Bootstrap](https://github.com/mbr/flask-bootstrap/)
[github-markdown-css](https://github.com/sindresorhus/github-markdown-css/)
[Bytesize Icons](https://github.com/danklammer/bytesize-icons/)
[RESTClient](https://github.com/chao/RESTClient/)
[examples]: https://github.com/kwkwc/flask-docs/tree/master/examples
[online_demo]: https://kwkwc.github.io/flask-docs-demo/
Raw data
{
"_id": null,
"home_page": "https://github.com/kwkwc/flask-docs",
"name": "Flask-Docs",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "flask, api, apidoc, doc, docs, documentation, md, markdown, RESTful, auto",
"author": "kwkw",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b3/04/1595d57e735fad536aa3d04f23b0830a6b75fe7f50de5cd731924a2d647d/flask_docs-0.7.6.tar.gz",
"platform": "any",
"description": "# Flask-Docs\n\n[](https://github.com/kwkwc/flask-docs/actions/workflows/test.yml)\n[](https://github.com/kwkwc/flask-docs/actions/workflows/publish.yml)\n[](https://codecov.io/gh/kwkwc/flask-docs)\n[](https://pypi.org/project/Flask-Docs/)\n[](https://pypi.org/project/Flask-Docs/)\n[](https://github.com/psf/black)\n\n[](https://github.com/kwkwc/flask-docs/blob/master/LICENSE)\n\n> Adds Docs support to Flask.\n\nEnglish | [\u7b80\u4f53\u4e2d\u6587](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`pip3 install Flask-Docs`\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\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\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\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 > 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 > 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&type=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\n\n\n\n## Flask MethodView API\n\n> **_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> 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\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",
"bugtrack_url": null,
"license": "MIT",
"summary": "Adds Docs support to Flask.",
"version": "0.7.6",
"project_urls": {
"Homepage": "https://github.com/kwkwc/flask-docs"
},
"split_keywords": [
"flask",
" api",
" apidoc",
" doc",
" docs",
" documentation",
" md",
" markdown",
" restful",
" auto"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cab8be216d59e83682ac931b25f0c06cf8614384b47a3504f6f4fc21cdc140a4",
"md5": "b8e0be5ba1db3ea9251d220260bff905",
"sha256": "c0e1ae06e8879113d1a2ef1b4f476f73ced8dffba014d2a1379d4f51daf6391e"
},
"downloads": -1,
"filename": "Flask_Docs-0.7.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8e0be5ba1db3ea9251d220260bff905",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 541074,
"upload_time": "2024-04-14T07:07:52",
"upload_time_iso_8601": "2024-04-14T07:07:52.033520Z",
"url": "https://files.pythonhosted.org/packages/ca/b8/be216d59e83682ac931b25f0c06cf8614384b47a3504f6f4fc21cdc140a4/Flask_Docs-0.7.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b3041595d57e735fad536aa3d04f23b0830a6b75fe7f50de5cd731924a2d647d",
"md5": "315dc40d04c30ee5e4c08c567c7a3374",
"sha256": "df579c9264c806ca484ba612041a0b0bb550109ecedf3a0ee252bffc486fc2a3"
},
"downloads": -1,
"filename": "flask_docs-0.7.6.tar.gz",
"has_sig": false,
"md5_digest": "315dc40d04c30ee5e4c08c567c7a3374",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 542406,
"upload_time": "2024-04-14T07:07:54",
"upload_time_iso_8601": "2024-04-14T07:07:54.033325Z",
"url": "https://files.pythonhosted.org/packages/b3/04/1595d57e735fad536aa3d04f23b0830a6b75fe7f50de5cd731924a2d647d/flask_docs-0.7.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 07:07:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kwkwc",
"github_project": "flask-docs",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "flask-docs"
}
JSON
