APIFlask 2.1.2__tar.gz → 2.1.4.dev0__tar.gz

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/CHANGES.md

@@ -1,3 +1,27 @@
+## Version 2.2.0
+
+Released: 2024/8/3
+
+- Fix deprecated warnings in tests ([issue #594][issue_594]).
+- Use postponed evaluation of annotations ([pr #585][pr_585]).
+- Add static OpenAPI docs example ([issue #587][issue_587]).
+- Add spec extensions support with `@doc(extensions=...)` for the view function ([issue #571][issue_571]).
+
+[pr_585]: https://github.com/apiflask/apiflask/pull/585
+[issue_594]: https://github.com/apiflask/apiflask/issues/594
+[issue_587]: https://github.com/apiflask/apiflask/issues/587
+[issue_571]: https://github.com/apiflask/apiflask/issues/571
+
+
+## Version 2.1.3
+
+Released: 2024/7/14
+
+- Fix the `flask spec` command for latest Flask ([issue #582][issue_582]).
+
+[issue_582]: https://github.com/apiflask/apiflask/issues/582
+
+
 ## Version 2.1.2
 
 Released: 2024/7/6

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: APIFlask
-Version: 2.1.2
+Version: 2.1.4.dev0
 Summary: A lightweight web API framework based on Flask and marshmallow-code projects.
 Author-email: Grey Li <withlihui@gmail.com>
 License: MIT
@@ -292,7 +292,7 @@ For some complete examples, see [/examples](https://github.com/apiflask/apiflask
 
 ## Relationship with Flask
 
-APIFlask is a thin wrapper on top of Flask. You only need to remember the following differences (see *[Migrating from Flask](https://apiflask.com/migrating)* for more details):
+APIFlask is a thin wrapper on top of Flask. You only need to remember the following differences (see *[Migrating from Flask](https://apiflask.com/migrations/flask/)* for more details):
 
 - When creating an application instance, use `APIFlask` instead of `Flask`.
 - When creating a blueprint instance, use `APIBlueprint` instead of `Blueprint`.

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/README.md

@@ -249,7 +249,7 @@ For some complete examples, see [/examples](https://github.com/apiflask/apiflask
 
 ## Relationship with Flask
 
-APIFlask is a thin wrapper on top of Flask. You only need to remember the following differences (see *[Migrating from Flask](https://apiflask.com/migrating)* for more details):
+APIFlask is a thin wrapper on top of Flask. You only need to remember the following differences (see *[Migrating from Flask](https://apiflask.com/migrations/flask/)* for more details):
 
 - When creating an application instance, use `APIFlask` instead of `Flask`.
 - When creating a blueprint instance, use `APIBlueprint` instead of `Blueprint`.

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/README.md

@@ -4,7 +4,7 @@
 - Class-based view example: [/examples/cbv/app.py][_cbv]
 - ORM example (with Flask-SQLAlchemy): [/examples/orm/app.py][_orm]
 - Pagination example (with Flask-SQLAlchemy): [/examples/pagination/app.py][_pagination]
-- OpenAPI example: [/examples/openapi][_openapi]
+- OpenAPI examples: [/examples/openapi][_openapi]
 - Base response example: [/examples/base_response/app.py][_base_response]
 - Token auth example: [/examples/auth/token_auth/app.py][_token_auth]
 - Basic auth example: [/examples/auth/basic_auth/app.py][_basic_auth]
@@ -65,6 +65,7 @@ Each example application store in a sub-folder:
 - `/pagination`: Pagination example (with Flask-SQLAlchemy)
 - `/openapi/basic`: Basic OpenAPI example
 - `/openapi/custom_decorators`: OpenAPI example with custom decorators
+- `/openapi/static_docs`: OpenAPI example with standalone static HTML OpenAPI docs
 - `/base_response`: Base response example
 - `/dataclass`: Dataclass example (with marshmallow-dataclass)
 

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/auth/basic_auth/app.py

@@ -14,10 +14,7 @@ users = {
 
 @auth.verify_password
 def verify_password(username: str, password: str) -> t.Union[str, None]:
-    if (
-        username in users
-        and check_password_hash(users[username], password)
-    ):
+    if username in users and check_password_hash(users[username], password):
         return username
     return None
 

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/auth/token_auth/app.py

@@ -16,12 +16,8 @@ class User:
 
     def get_token(self):
         header = {'alg': 'HS256'}
-        payload = {
-            'id': self.id
-        }
-        return jwt.encode(
-            header, payload, current_app.config['SECRET_KEY']
-        ).decode()
+        payload = {'id': self.id}
+        return jwt.encode(header, payload, current_app.config['SECRET_KEY']).decode()
 
 
 users = [
@@ -60,9 +56,7 @@ class Token(Schema):
 def get_token(id: int):
     if get_user_by_id(id) is None:
         abort(404)
-    return {
-        'token': f'Bearer {get_user_by_id(id).get_token()}'
-    }
+    return {'token': f'Bearer {get_user_by_id(id).get_token()}'}
 
 
 @app.get('/name/<int:id>')

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/base_response/app.py

@@ -19,7 +19,7 @@ app.config['BASE_RESPONSE_DATA_KEY'] = 'data'
 pets = [
     {'id': 0, 'name': 'Kitty', 'category': 'cat'},
     {'id': 1, 'name': 'Coco', 'category': 'dog'},
-    {'id': 2, 'name': 'Flash', 'category': 'cat'}
+    {'id': 2, 'name': 'Flash', 'category': 'cat'},
 ]
 
 
@@ -37,11 +37,7 @@ class PetOut(Schema):
 @app.get('/')
 def say_hello():
     data = {'message': 'Hello!'}
-    return {
-        'data': data,
-        'message': 'Success!',
-        'code': 200
-    }
+    return {'data': data, 'message': 'Success!', 'code': 200}
 
 
 @app.get('/pets/<int:pet_id>')
@@ -73,11 +69,7 @@ def create_pet(json_data):
     pet_id = len(pets)
     json_data['id'] = pet_id
     pets.append(json_data)
-    return {
-        'data': pets[pet_id],
-        'message': 'Pet created.',
-        'code': 201
-    }
+    return {'data': pets[pet_id], 'message': 'Pet created.', 'code': 201}
 
 
 @app.patch('/pets/<int:pet_id>')
@@ -88,11 +80,7 @@ def update_pet(pet_id, json_data):
         abort(404)
     for attr, value in json_data.items():
         pets[pet_id][attr] = value
-    return {
-        'data': pets[pet_id],
-        'message': 'Pet updated.',
-        'code': 200
-    }
+    return {'data': pets[pet_id], 'message': 'Pet updated.', 'code': 200}
 
 
 @app.delete('/pets/<int:pet_id>')

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/basic/app.py

@@ -7,7 +7,7 @@ app = APIFlask(__name__)
 pets = [
     {'id': 0, 'name': 'Kitty', 'category': 'cat'},
     {'id': 1, 'name': 'Coco', 'category': 'dog'},
-    {'id': 2, 'name': 'Flash', 'category': 'cat'}
+    {'id': 2, 'name': 'Flash', 'category': 'cat'},
 ]
 
 

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/blueprint_tags/app.py

@@ -16,7 +16,7 @@ pet_bp = APIBlueprint('pet', __name__)  # tag name will be "Pet"
 pets = [
     {'id': 0, 'name': 'Kitty', 'category': 'cat'},
     {'id': 1, 'name': 'Coco', 'category': 'dog'},
-    {'id': 2, 'name': 'Flash', 'category': 'cat'}
+    {'id': 2, 'name': 'Flash', 'category': 'cat'},
 ]
 
 

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/cbv/app.py

@@ -8,7 +8,7 @@ app = APIFlask(__name__)
 pets = [
     {'id': 0, 'name': 'Kitty', 'category': 'cat'},
     {'id': 1, 'name': 'Coco', 'category': 'dog'},
-    {'id': 2, 'name': 'Flash', 'category': 'cat'}
+    {'id': 2, 'name': 'Flash', 'category': 'cat'},
 ]
 
 
@@ -24,13 +24,11 @@ class PetOut(Schema):
 
 
 class Hello(MethodView):
-
     def get(self):
         return {'message': 'Hello!'}
 
 
 class Pet(MethodView):
-
     @app.output(PetOut)
     def get(self, pet_id):
         """Get a pet"""
@@ -59,7 +57,6 @@ class Pet(MethodView):
 
 
 class Pets(MethodView):
-
     @app.output(PetOut(many=True))
     def get(self):
         """Get all pets"""

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/dataclass/app.py

@@ -13,18 +13,16 @@ class PetIn:
         metadata={
             'required': True,
             'validate': Length(min=1, max=10),
-            'example': 'Medor',
-            'description': 'This will be printed in the generated doc. '
-                           'The "example" value "Medor" will be fed '
-                           'into the "try it"/"Send API request".',
+            'metadata': {
+                'example': 'Medor',
+                'description': 'This will be printed in the generated doc. '
+                'The "example" value "Medor" will be fed '
+                'into the "try it"/"Send API request".',
+            },
         }
     )
     category: str = field(
-        default='dog',
-        metadata={
-            'required': True,
-            'validate': OneOf(['cat', 'dog'])
-        }
+        default='dog', metadata={'required': True, 'validate': OneOf(['cat', 'dog'])}
     )
 
 
@@ -38,7 +36,7 @@ class PetOut:
 pets = [
     {'id': 0, 'name': 'Kitty', 'category': 'cat'},
     {'id': 1, 'name': 'Coco', 'category': 'dog'},
-    {'id': 2, 'name': 'Flash', 'category': 'cat'}
+    {'id': 2, 'name': 'Flash', 'category': 'cat'},
 ]
 
 
@@ -66,11 +64,7 @@ def get_pets():
 @app.output(PetOut.Schema, status_code=201)
 def create_pet(pet: PetIn):
     pet_id = len(pets)
-    pets.append({
-        'id': pet_id,
-        'name': pet.name,
-        'category': pet.category
-    })
+    pets.append({'id': pet_id, 'name': pet.name, 'category': pet.category})
     return pets[pet_id]
 
 

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/openapi/basic/app.py

@@ -31,14 +31,11 @@ The source can be found at [examples/blueprint_tags/app.py][_blueprint_tags].
 app.config['CONTACT'] = {
     'name': 'API Support',
     'url': 'https://greyli.com/en',
-    'email': 'withlihui@gmail.com'
+    'email': 'withlihui@gmail.com',
 }
 
 # openapi.info.license
-app.config['LICENSE'] = {
-    'name': 'MIT',
-    'url': 'https://opensource.org/licenses/MIT'
-}
+app.config['LICENSE'] = {'name': 'MIT', 'url': 'https://opensource.org/licenses/MIT'}
 
 # openapi.info.termsOfService
 app.config['TERMS_OF_SERVICE'] = 'http://example.com'
@@ -61,7 +58,7 @@ app.config['TERMS_OF_SERVICE'] = 'http://example.com'
 # openapi.tags
 app.config['TAGS'] = [
     {'name': 'Hello', 'description': 'The description of the **Hello** tag.'},
-    {'name': 'Pet', 'description': 'The description of the **Pet** tag.'}
+    {'name': 'Pet', 'description': 'The description of the **Pet** tag.'},
 ]
 
 # If you don't need to set tag "description" or tag "externalDocs", just pass a list a string:
@@ -69,30 +66,21 @@ app.config['TAGS'] = [
 
 # openapi.servers
 app.config['SERVERS'] = [
-    {
-        'name': 'Development Server',
-        'url': 'http://localhost:5000'
-    },
-    {
-        'name': 'Production Server',
-        'url': 'http://api.example.com'
-    },
-    {
-        'name': 'Testing Server',
-        'url': 'http://test.example.com'
-    }
+    {'name': 'Development Server', 'url': 'http://localhost:5000'},
+    {'name': 'Production Server', 'url': 'http://api.example.com'},
+    {'name': 'Testing Server', 'url': 'http://test.example.com'},
 ]
 
 # openapi.externalDocs
 app.config['EXTERNAL_DOCS'] = {
     'description': 'Find more info here',
-    'url': 'https://apiflask.com/docs'
+    'url': 'https://apiflask.com/docs',
 }
 
 pets = [
     {'id': 0, 'name': 'Kitty', 'category': 'cat'},
     {'id': 1, 'name': 'Coco', 'category': 'dog'},
-    {'id': 2, 'name': 'Flash', 'category': 'cat'}
+    {'id': 2, 'name': 'Flash', 'category': 'cat'},
 ]
 
 
@@ -100,12 +88,12 @@ class PetIn(Schema):
     name = String(
         required=True,
         validate=Length(0, 10),
-        metadata={'title': 'Pet Name', 'description': 'The name of the pet.'}
+        metadata={'title': 'Pet Name', 'description': 'The name of the pet.'},
     )
     category = String(
         required=True,
         validate=OneOf(['dog', 'cat']),
-        metadata={'title': 'Pet Category', 'description': 'The category of the pet.'}
+        metadata={'title': 'Pet Category', 'description': 'The category of the pet.'},
     )
 
 
@@ -158,12 +146,7 @@ def get_pets():
     PetOut,
     status_code=201,
     description='The pet you just created',
-    links={'getPetById': {
-        'operationId': 'getPet',
-        'parameters': {
-            'pet_id': '$response.body#/id'
-        }
-    }}
+    links={'getPetById': {'operationId': 'getPet', 'parameters': {'pet_id': '$response.body#/id'}}},
 )
 @app.doc(tags=['Pet'])
 def create_pet(json_data):

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/openapi/custom_decorators/app.py

@@ -23,10 +23,7 @@ app.config['DOCS_DECORATORS'] = [app.auth_required(auth)]
 
 @auth.verify_password
 def verify_password(username: str, password: str) -> t.Union[str, None]:
-    if (
-        username in users
-        and check_password_hash(users[username], password)
-    ):
+    if username in users and check_password_hash(users[username], password):
         return username
     return None
 

apiflask-2.1.4.dev0/examples/openapi/static_docs/app.py

@@ -0,0 +1,54 @@
+from apiflask import APIFlask, Schema, abort
+from apiflask.fields import Integer, String
+from apiflask.validators import Length, OneOf
+
+app = APIFlask(__name__)
+app.config['SYNC_LOCAL_SPEC'] = True
+app.config['LOCAL_SPEC_PATH'] = 'openapi.json'
+app.config['LOCAL_SPEC_JSON_INDENT'] = 0
+
+pets = [{'id': 0, 'name': 'Kitty', 'category': 'cat'}, {'id': 1, 'name': 'Coco', 'category': 'dog'}]
+
+
+class PetIn(Schema):
+    name = String(required=True, validate=Length(0, 10))
+    category = String(required=True, validate=OneOf(['dog', 'cat']))
+
+
+class PetOut(Schema):
+    id = Integer()
+    name = String()
+    category = String()
+
+
+@app.get('/')
+def say_hello():
+    # returning a dict or list equals to use jsonify()
+    return {'message': 'Hello!'}
+
+
+@app.get('/pets/<int:pet_id>')
+@app.output(PetOut)
+def get_pet(pet_id):
+    if pet_id > len(pets) - 1:
+        abort(404)
+    # you can also return an ORM/ODM model class instance directly
+    # APIFlask will serialize the object into JSON format
+    return pets[pet_id]
+
+
+@app.patch('/pets/<int:pet_id>')
+@app.input(PetIn(partial=True))  # -> json_data
+@app.output(PetOut)
+def update_pet(pet_id, json_data):
+    # the validated and parsed input data will
+    # be injected into the view function as a dict
+    if pet_id > len(pets) - 1:
+        abort(404)
+    for attr, value in json_data.items():
+        pets[pet_id][attr] = value
+    return pets[pet_id]
+
+
+if __name__ == '__main__':
+    app.run()

apiflask-2.1.4.dev0/examples/openapi/static_docs/generate_docs.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+spec_value=$(python3 -c "import json; print(open('openapi.json').read())")
+# Replace var spec = {...} line in index.html
+sed -i "s|var spec = {.*}|var spec = $spec_value|g" index.html
+echo "Swagger HTML generated successfully!"
+echo "Open index.html in your browser to view the Swagger UI."

apiflask-2.1.4.dev0/examples/openapi/static_docs/index.html

@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>APIFlask 0.1.0 - Swagger UI</title>
+  <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css">
+  <link rel="icon" type="image/png"
+    href="https://apiflask.com/_assets/favicon.png">
+  <style>
+    html {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+
+    *,
+    *:before,
+    *:after {
+      box-sizing: inherit;
+    }
+
+    body {
+      margin: 0;
+      background: #fafafa;
+    }
+  </style>
+</head>
+
+<body>
+  <div id="swagger-ui"></div>
+
+  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
+  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-standalone-preset.js"></script>
+  <script>
+    // we can get several config items of Function type
+    // referring to https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
+    var funcConfigItems = ['operationsSorter', 'tagsSorter', 'onComplete', 'requestInterceptor', 'responseInterceptor', 'modelPropertyMacro', 'parameterMacro']
+
+    function parseFunc(funcStr) {
+        return new Function('"use strict"; return ' + funcStr)()
+    }
+
+    var spec = {"components": {"schemas": {"HTTPError": {"properties": {"detail": {"type": "object"}, "message": {"type": "string"}}, "type": "object"}, "PetInUpdate": {"properties": {"category": {"enum": ["dog", "cat"], "type": "string"}, "name": {"maxLength": 10, "minLength": 0, "type": "string"}}, "type": "object"}, "PetOut": {"properties": {"category": {"type": "string"}, "id": {"type": "integer"}, "name": {"type": "string"}}, "type": "object"}, "ValidationError": {"properties": {"detail": {"properties": {"<location>": {"properties": {"<field_name>": {"items": {"type": "string"}, "type": "array"}}, "type": "object"}}, "type": "object"}, "message": {"type": "string"}}, "type": "object"}}}, "info": {"title": "APIFlask", "version": "0.1.0"}, "openapi": "3.0.3", "paths": {"/": {"get": {"parameters": [], "responses": {"200": {"content": {"application/json": {"schema": {}}}, "description": "Successful response"}}, "summary": "Say Hello"}}, "/pets/{pet_id}": {"get": {"parameters": [{"in": "path", "name": "pet_id", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/PetOut"}}}, "description": "Successful response"}, "404": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPError"}}}, "description": "Not found"}}, "summary": "Get Pet"}, "patch": {"parameters": [{"in": "path", "name": "pet_id", "required": true, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/PetInUpdate"}}}}, "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/PetOut"}}}, "description": "Successful response"}, "404": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPError"}}}, "description": "Not found"}, "422": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ValidationError"}}}, "description": "Validation error"}}, "summary": "Update Pet"}}}, "tags": []}
+
+    var baseConfig = {
+      spec: spec,
+      dom_id: "#swagger-ui",
+      deepLinking: true,
+      presets: [
+        SwaggerUIBundle.presets.apis,
+        SwaggerUIStandalonePreset
+      ],
+      plugins: [
+        SwaggerUIBundle.plugins.DownloadUrl
+      ],
+      layout: "BaseLayout",
+        oauth2RedirectUrl: "/docs/oauth2-redirect"
+    }
+
+    window.onload = function () {
+      const ui = SwaggerUIBundle(baseConfig)
+
+    }
+  </script>
+</body>
+
+</html>

apiflask-2.1.4.dev0/examples/openapi/static_docs/openapi.json

@@ -0,0 +1 @@
+{"components": {"schemas": {"HTTPError": {"properties": {"detail": {"type": "object"}, "message": {"type": "string"}}, "type": "object"}, "PetInUpdate": {"properties": {"category": {"enum": ["dog", "cat"], "type": "string"}, "name": {"maxLength": 10, "minLength": 0, "type": "string"}}, "type": "object"}, "PetOut": {"properties": {"category": {"type": "string"}, "id": {"type": "integer"}, "name": {"type": "string"}}, "type": "object"}, "ValidationError": {"properties": {"detail": {"properties": {"<location>": {"properties": {"<field_name>": {"items": {"type": "string"}, "type": "array"}}, "type": "object"}}, "type": "object"}, "message": {"type": "string"}}, "type": "object"}}}, "info": {"title": "APIFlask", "version": "0.1.0"}, "openapi": "3.0.3", "paths": {"/": {"get": {"parameters": [], "responses": {"200": {"content": {"application/json": {"schema": {}}}, "description": "Successful response"}}, "summary": "Say Hello"}}, "/pets/{pet_id}": {"get": {"parameters": [{"in": "path", "name": "pet_id", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/PetOut"}}}, "description": "Successful response"}, "404": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPError"}}}, "description": "Not found"}}, "summary": "Get Pet"}, "patch": {"parameters": [{"in": "path", "name": "pet_id", "required": true, "schema": {"type": "integer"}}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/PetInUpdate"}}}}, "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/PetOut"}}}, "description": "Successful response"}, "404": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/HTTPError"}}}, "description": "Not found"}, "422": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ValidationError"}}}, "description": "Validation error"}}, "summary": "Update Pet"}}}, "tags": []}

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/orm/app.py

@@ -22,7 +22,7 @@ def init_database():
     pets = [
         {'name': 'Kitty', 'category': 'cat'},
         {'name': 'Coco', 'category': 'dog'},
-        {'name': 'Flash', 'category': 'cat'}
+        {'name': 'Flash', 'category': 'cat'},
     ]
     for pet_data in pets:
         pet = PetModel(**pet_data)

{apiflask-2.1.2 → apiflask-2.1.4.dev0}/examples/pagination/app.py

@@ -60,15 +60,10 @@ def get_pet(pet_id):
 @app.output(PetsOut)
 def get_pets(query_data):
     pagination = db.paginate(
-        db.select(PetModel),
-        page=query_data['page'],
-        per_page=query_data['per_page']
+        db.select(PetModel), page=query_data['page'], per_page=query_data['per_page']
     )
     pets = pagination.items
-    return {
-        'pets': pets,
-        'pagination': pagination_builder(pagination)
-    }
+    return {'pets': pets, 'pagination': pagination_builder(pagination)}
 
 
 with app.app_context():