Skip to content

Quickstart

flask_openapi3 based on Flask and Pydantic, So you can use it like Flask.

A Minimal Application⚓︎

Just like Flask, Create hello.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from flask_openapi3 import OpenAPI

app = OpenAPI(__name__)


@app.route('/')
def hello_world():
    return 'Hello, World!'


if __name__ == '__main__':
    app.run()

And then run it:

1
python hello.py

You will see the output information:

1
2
3
4
5
6
 * Serving Flask app 'just_flask' (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

REST API⚓︎

You can use get, post, put, patch, delete REST API in flask-openapi3.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from flask_openapi3 import OpenAPI

app = OpenAPI(__name__)


@app.get('/book')
def get_books():
    return ["book1", "book2"]


@app.post('/book')
def create_book():
    return {"message": "success"}


if __name__ == '__main__':
    app.run()

APIBlueprint⚓︎

APIBlueprint based on Flask Blueprint, you should use register_api instead of register_blueprint.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from flask_openapi3 import OpenAPI

app = OpenAPI(__name__)

api = APIBlueprint('book', __name__, url_prefix='/api')


@api.post('/book')
def create_book():
    return {"message": "success"}


# register api
app.register_api(api)

if __name__ == '__main__':
    app.run()

Nested APIBlueprint⚓︎

New in v2.0.0

Allow an API Blueprint to be registered on another API Blueprint.

For more information, please see Flask Nesting Blueprints.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
from flask_openapi3 import OpenAPI, APIBlueprint

app = OpenAPI(__name__)

api = APIBlueprint('book', __name__, url_prefix='/api/book')
api_english = APIBlueprint('english', __name__)
api_chinese = APIBlueprint('chinese', __name__)


@api_english.post('/english')
def create_english_book():
    return {"message": "english"}


@api_chinese.post('/chinese')
def create_chinese_book():
    return {"message": "chinese"}


# register nested api
api.register_api(api_english)
api.register_api(api_chinese)
# register api
app.register_api(api)

if __name__ == '__main__':
    app.run(debug=True)

APIView⚓︎

New in v2.2.0

Class-based API View, click here for the complete example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
@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.json()

    @api_view.doc(summary="create book")
    def post(self, body: BookBody):
        """description for a created book"""
        return body.json()

New in v2.4.0

You can define a parameter named view_kwargs (the only parameter of the __init__ function), and using view_kwargs.get get the required keys for each.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
@api_view.route("/book")
class BookListAPIView:
    def __init__(self, view_kwargs=None):
        self.a = view_kwargs.get("a")

    def get(self):
        ...

    def post(self):
        ...

@api_view.route("/book/<id>")
class BookAPIView:
    def __init__(self, view_kwargs=None):
        self.b = view_kwargs.get("b")

    def get(self):
        ...

    def put(self):
        ...

    def delete(self):
        ...

app.register_api_view(
    api_view,
    view_kwargs={
        "a": 1,
        "b": 2
    }
)

Async API⚓︎

New in v2.2.2

Just use async when defining functions. More information goes to Using async and await — Flask Documentation.

Info

You need to manually install asgiref using pip: 

1
2
3
4
pip install flask-openapi3[async]

# or
pip install asgiref


1
2
3
4
@app.post('/open/api')
async def post_openapi(body: Query):
    print(body)
    return 'POST, OpenAPI!'