| Name | flask-openapi3 JSON |
| Version |
3.1.1
JSON |
| download |
| home_page | None |
| Summary | Generate REST API and OpenAPI documentation for your Flask project. |
| upload_time | 2024-04-21 03:08:14 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<a href="https://luolingchun.github.io/flask-openapi3/" target="_blank">
<img class="off-glb" src="https://raw.githubusercontent.com/luolingchun/flask-openapi3/master/docs/images/logo-text.svg"
width="60%" height="auto" alt="logo">
</a>
</div>
<p align="center">
<em>Generate REST API and OpenAPI documentation for your Flask project.</em>
</p>
<p align="center">
<a href="https://github.com/luolingchun/flask-openapi3/actions/workflows/tests.yml" target="_blank">
<img class="off-glb" src="https://img.shields.io/github/actions/workflow/status/luolingchun/flask-openapi3/tests.yml?branch=master" alt="test">
</a>
<a href="https://pypi.org/project/flask-openapi3/" target="_blank">
<img class="off-glb" src="https://img.shields.io/pypi/v/flask-openapi3" alt="pypi">
</a>
<a href="https://pypistats.org/packages/flask-openapi3" target="_blank">
<img class="off-glb" src="https://img.shields.io/pypi/dm/flask-openapi3" alt="pypistats">
</a>
<a href="https://pypi.org/project/flask-openapi3/" target="_blank">
<img class="off-glb" src="https://img.shields.io/pypi/pyversions/flask-openapi3" alt="pypi versions">
</a>
</p>
**Flask OpenAPI3** is a web API framework based on **Flask**. It uses **Pydantic** to verify data and automatic
generation of interaction documentation: **Swagger**, **ReDoc** and **RapiDoc**.
The key features are:
- **Easy to code:** Easy to use and easy to learn
- **Standard document specification:** Based on [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0)
- **Interactive OpenAPI documentation:** [Swagger](https://github.com/swagger-api/swagger-ui), [Redoc](https://github.com/Redocly/redoc) and [RapiDoc](https://github.com/rapi-doc/RapiDoc)
- **Data validation:** Fast data verification based on [Pydantic](https://github.com/pydantic/pydantic)
- **Authorization:** Support to reload authorizations in Swagger UI
## Requirements
Python 3.8+
flask-openapi3 is dependent on the following libraries:
- [Flask](https://github.com/pallets/flask) for the web app.
- [Pydantic](https://github.com/pydantic/pydantic) for the data validation.
## Installation
```bash
pip install -U flask-openapi3
```
or
```bash
conda install -c conda-forge flask-openapi3
```
<details markdown="block">
<summary>Optional dependencies</summary>
- [python-email-validator](https://github.com/JoshData/python-email-validator) supports email verification.
- [python-dotenv](https://github.com/theskumar/python-dotenv#readme) enables support for [Environment Variables From dotenv](https://flask.palletsprojects.com/en/latest/cli/#dotenv) when running `flask` commands.
- [pyyaml](https://github.com/yaml/pyyaml) is used to output the OpenAPI document in yaml format.
- [asgiref](https://github.com/django/asgiref) allows views to be defined with `async def` and use `await`.
To install these dependencies with flask-openapi3:
```bash
pip install flask-openapi3[yaml]
# or
pip install flask-openapi3[async]
# or
pip install flask-openapi3[dotenv]
# or
pip install flask-openapi3[email]
# or all
pip install flask-openapi3[yaml,async,dotenv,email]
# or manually
pip install pyyaml asgiref python-dotenv email-validator
```
</details>
## A Simple Example
Here's a simple example, further go to the [Example](https://luolingchun.github.io/flask-openapi3/latest/Example/).
```python
from pydantic import BaseModel
from flask_openapi3 import Info, Tag
from flask_openapi3 import OpenAPI
info = Info(title="book API", version="1.0.0")
app = OpenAPI(__name__, info=info)
book_tag = Tag(name="book", description="Some Book")
class BookQuery(BaseModel):
age: int
author: str
@app.get("/book", summary="get books", tags=[book_tag])
def get_book(query: BookQuery):
"""
to get all books
"""
return {
"code": 0,
"message": "ok",
"data": [
{"bid": 1, "age": query.age, "author": query.author},
{"bid": 2, "age": query.age, "author": query.author}
]
}
if __name__ == "__main__":
app.run(debug=True)
```
<details>
<summary>Class-based API View Example</summary>
```python
from typing import Optional
from pydantic import BaseModel, Field
from flask_openapi3 import OpenAPI, Tag, Info, APIView
info = Info(title='book API', version='1.0.0')
app = OpenAPI(__name__, info=info)
api_view = APIView(url_prefix="/api/v1", view_tags=[Tag(name="book")])
class BookPath(BaseModel):
id: int = Field(..., description="book ID")
class BookQuery(BaseModel):
age: Optional[int] = Field(None, description='Age')
class BookBody(BaseModel):
age: Optional[int] = Field(..., ge=2, le=4, description='Age')
author: str = Field(None, min_length=2, max_length=4, description='Author')
@api_view.route("/book")
class BookListAPIView:
a = 1
@api_view.doc(summary="get book list")
def get(self, query: BookQuery):
print(self.a)
return query.model_dump_json()
@api_view.doc(summary="create book")
def post(self, body: BookBody):
"""description for a created book"""
return body.model_dump_json()
@api_view.route("/book/<id>")
class BookAPIView:
@api_view.doc(summary="get book")
def get(self, path: BookPath):
print(path)
return "get"
@api_view.doc(summary="update book")
def put(self, path: BookPath):
print(path)
return "put"
@api_view.doc(summary="delete book", deprecated=True)
def delete(self, path: BookPath):
print(path)
return "delete"
app.register_api_view(api_view)
if __name__ == "__main__":
app.run(debug=True)
```
</details>
## API Document
Run the [simple example](https://github.com/luolingchun/flask-openapi3/blob/master/examples/simple_demo.py), and go to http://127.0.0.1:5000/openapi.
You will see the documentation: [Swagger](https://github.com/swagger-api/swagger-ui), [Redoc](https://github.com/Redocly/redoc) and [RapiDoc](https://github.com/rapi-doc/RapiDoc).
Raw data
{
"_id": null,
"home_page": null,
"name": "flask-openapi3",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "llc <luolingchun@outlook.com>",
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ec/d3/c09719c389086de7a9754be9dde0e6178ec0390b2e20fe7c5645963d3d6f/flask_openapi3-3.1.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <a href=\"https://luolingchun.github.io/flask-openapi3/\" target=\"_blank\">\n <img class=\"off-glb\" src=\"https://raw.githubusercontent.com/luolingchun/flask-openapi3/master/docs/images/logo-text.svg\" \n width=\"60%\" height=\"auto\" alt=\"logo\">\n </a>\n</div>\n<p align=\"center\">\n <em>Generate REST API and OpenAPI documentation for your Flask project.</em>\n</p>\n<p align=\"center\">\n <a href=\"https://github.com/luolingchun/flask-openapi3/actions/workflows/tests.yml\" target=\"_blank\">\n <img class=\"off-glb\" src=\"https://img.shields.io/github/actions/workflow/status/luolingchun/flask-openapi3/tests.yml?branch=master\" alt=\"test\">\n </a>\n <a href=\"https://pypi.org/project/flask-openapi3/\" target=\"_blank\">\n <img class=\"off-glb\" src=\"https://img.shields.io/pypi/v/flask-openapi3\" alt=\"pypi\">\n </a>\n <a href=\"https://pypistats.org/packages/flask-openapi3\" target=\"_blank\">\n <img class=\"off-glb\" src=\"https://img.shields.io/pypi/dm/flask-openapi3\" alt=\"pypistats\">\n </a>\n <a href=\"https://pypi.org/project/flask-openapi3/\" target=\"_blank\">\n <img class=\"off-glb\" src=\"https://img.shields.io/pypi/pyversions/flask-openapi3\" alt=\"pypi versions\">\n </a>\n</p>\n\n**Flask OpenAPI3** is a web API framework based on **Flask**. It uses **Pydantic** to verify data and automatic\ngeneration of interaction documentation: **Swagger**, **ReDoc** and **RapiDoc**.\n\nThe key features are:\n\n- **Easy to code:** Easy to use and easy to learn\n\n- **Standard document specification:** Based on [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0)\n\n- **Interactive OpenAPI documentation:** [Swagger](https://github.com/swagger-api/swagger-ui), [Redoc](https://github.com/Redocly/redoc) and [RapiDoc](https://github.com/rapi-doc/RapiDoc)\n \n- **Data validation:** Fast data verification based on [Pydantic](https://github.com/pydantic/pydantic)\n\n- **Authorization:** Support to reload authorizations in Swagger UI\n\n## Requirements\n\nPython 3.8+\n\nflask-openapi3 is dependent on the following libraries:\n\n- [Flask](https://github.com/pallets/flask) for the web app.\n- [Pydantic](https://github.com/pydantic/pydantic) for the data validation.\n\n## Installation\n\n```bash\npip install -U flask-openapi3\n```\n\nor\n\n```bash\nconda install -c conda-forge flask-openapi3\n```\n\n<details markdown=\"block\">\n<summary>Optional dependencies</summary>\n\n- [python-email-validator](https://github.com/JoshData/python-email-validator) supports email verification.\n- [python-dotenv](https://github.com/theskumar/python-dotenv#readme) enables support for [Environment Variables From dotenv](https://flask.palletsprojects.com/en/latest/cli/#dotenv) when running `flask` commands.\n- [pyyaml](https://github.com/yaml/pyyaml) is used to output the OpenAPI document in yaml format.\n- [asgiref](https://github.com/django/asgiref) allows views to be defined with `async def` and use `await`.\n\nTo install these dependencies with flask-openapi3:\n\n```bash\npip install flask-openapi3[yaml]\n# or\npip install flask-openapi3[async]\n# or\npip install flask-openapi3[dotenv]\n# or\npip install flask-openapi3[email]\n# or all\npip install flask-openapi3[yaml,async,dotenv,email]\n# or manually\npip install pyyaml asgiref python-dotenv email-validator\n```\n</details>\n\n## A Simple Example\n\nHere's a simple example, further go to the [Example](https://luolingchun.github.io/flask-openapi3/latest/Example/).\n\n```python\nfrom pydantic import BaseModel\n\nfrom flask_openapi3 import Info, Tag\nfrom flask_openapi3 import OpenAPI\n\ninfo = Info(title=\"book API\", version=\"1.0.0\")\napp = OpenAPI(__name__, info=info)\n\nbook_tag = Tag(name=\"book\", description=\"Some Book\")\n\n\nclass BookQuery(BaseModel):\n age: int\n author: str\n\n\n@app.get(\"/book\", summary=\"get books\", tags=[book_tag])\ndef get_book(query: BookQuery):\n \"\"\"\n to get all books\n \"\"\"\n return {\n \"code\": 0,\n \"message\": \"ok\",\n \"data\": [\n {\"bid\": 1, \"age\": query.age, \"author\": query.author},\n {\"bid\": 2, \"age\": query.age, \"author\": query.author}\n ]\n }\n\n\nif __name__ == \"__main__\":\n app.run(debug=True)\n```\n\n<details>\n<summary>Class-based API View Example</summary>\n\n```python\nfrom typing import Optional\n\nfrom pydantic import BaseModel, Field\n\nfrom flask_openapi3 import OpenAPI, Tag, Info, APIView\n\n\ninfo = Info(title='book API', version='1.0.0')\napp = OpenAPI(__name__, info=info)\n\napi_view = APIView(url_prefix=\"/api/v1\", view_tags=[Tag(name=\"book\")])\n\n\nclass BookPath(BaseModel):\n id: int = Field(..., description=\"book ID\")\n\n\nclass BookQuery(BaseModel):\n age: Optional[int] = Field(None, description='Age')\n\n\nclass BookBody(BaseModel):\n age: Optional[int] = Field(..., ge=2, le=4, description='Age')\n author: str = Field(None, min_length=2, max_length=4, description='Author')\n\n\n@api_view.route(\"/book\")\nclass BookListAPIView:\n a = 1\n\n @api_view.doc(summary=\"get book list\")\n def get(self, query: BookQuery):\n print(self.a)\n return query.model_dump_json()\n\n @api_view.doc(summary=\"create book\")\n def post(self, body: BookBody):\n \"\"\"description for a created book\"\"\"\n return body.model_dump_json()\n\n\n@api_view.route(\"/book/<id>\")\nclass BookAPIView:\n @api_view.doc(summary=\"get book\")\n def get(self, path: BookPath):\n print(path)\n return \"get\"\n\n @api_view.doc(summary=\"update book\")\n def put(self, path: BookPath):\n print(path)\n return \"put\"\n\n @api_view.doc(summary=\"delete book\", deprecated=True)\n def delete(self, path: BookPath):\n print(path)\n return \"delete\"\n\n\napp.register_api_view(api_view)\n\nif __name__ == \"__main__\":\n app.run(debug=True)\n```\n</details>\n\n## API Document\n\nRun the [simple example](https://github.com/luolingchun/flask-openapi3/blob/master/examples/simple_demo.py), and go to http://127.0.0.1:5000/openapi.\n\nYou will see the documentation: [Swagger](https://github.com/swagger-api/swagger-ui), [Redoc](https://github.com/Redocly/redoc) and [RapiDoc](https://github.com/rapi-doc/RapiDoc).\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate REST API and OpenAPI documentation for your Flask project.",
"version": "3.1.1",
"project_urls": {
"Documentation": "https://luolingchun.github.io/flask-openapi3",
"Homepage": "https://github.com/luolingchun/flask-openapi3"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f31012baeaf09f58c669c490cece85503501611e4c6bc8b0be0063ee943e3ff9",
"md5": "9d18f89a37f76d2511c8af83dd8cfeb2",
"sha256": "41b44e99737814070fbfe4d88402b0da412e44dfaefd581f92d9c63206da77fc"
},
"downloads": -1,
"filename": "flask_openapi3-3.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9d18f89a37f76d2511c8af83dd8cfeb2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 996152,
"upload_time": "2024-04-21T03:08:12",
"upload_time_iso_8601": "2024-04-21T03:08:12.325158Z",
"url": "https://files.pythonhosted.org/packages/f3/10/12baeaf09f58c669c490cece85503501611e4c6bc8b0be0063ee943e3ff9/flask_openapi3-3.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ecd3c09719c389086de7a9754be9dde0e6178ec0390b2e20fe7c5645963d3d6f",
"md5": "a37692990f43c1160908744351bf019b",
"sha256": "6d6acdaa20b86ca1cfd92414a1a69998777f042bfab97b9c274ca4189868391a"
},
"downloads": -1,
"filename": "flask_openapi3-3.1.1.tar.gz",
"has_sig": false,
"md5_digest": "a37692990f43c1160908744351bf019b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 991023,
"upload_time": "2024-04-21T03:08:14",
"upload_time_iso_8601": "2024-04-21T03:08:14.220184Z",
"url": "https://files.pythonhosted.org/packages/ec/d3/c09719c389086de7a9754be9dde0e6178ec0390b2e20fe7c5645963d3d6f/flask_openapi3-3.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-21 03:08:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "luolingchun",
"github_project": "flask-openapi3",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flask-openapi3"
}
