Merge branch '2.x'

Author: luolingchun

.github/workflows/test.yml

@@ -28,7 +28,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-          pip install pytest flake8
+          pip install pytest flake8 openapi-python-client
           pip install -e .
       - name: Test with pytest
         run: |

CHANGELOG.md

@@ -1,11 +1,19 @@
+## 2.0.0 2022-??-??
+
+- [#17](https://github.com/luolingchun/flask-openapi3/issues/17) Support for Nested APIBlueprint enhancement. Thanks @dvaerum
+- [#23](https://github.com/luolingchun/flask-openapi3/pull/23) Fixed externalDocs support. Thanks @dvaerum
+- Add `flask openapi` command
+- Remove export markdown to `flask openapi` command
+- Upgrade flask to v2.0
+
 ## v1.1.4 2022-05-05
 
 - fix: Trailing slash in APIBlueprint
 
 ## v1.1.3 2022-05-01
 
 - fix: Find globalns for the unwrapped func
-- [#19](https://github.com/luolingchun/flask-openapi3/issues/19) fix: Trailing slash in APIBlueprint. Thinks @ev-agelos
+- [#19](https://github.com/luolingchun/flask-openapi3/issues/19) fix: Trailing slash in APIBlueprint. Thanks @ev-agelos
 - add description for UnprocessableEntity
 - remove printouts in `__init__.py`
 

docs/OpenAPI/Specification.md

@@ -1,5 +1,47 @@
+## Specification
+
 If you need the complete Specification(json) , go to http://127.0.0.1:5000/openapi/openapi.json
 
+**command: `flask openapi`**
+
+*New in v2.0.0*
+
+The `flask openapi` command will export the OpenAPI Specification to console when you execute the command:
+
+```
+flask openapi
+```
+
+Execute `flask openapi --help` for more information:
+
+```
+flask openapi --help
+
+Usage: flask openapi [OPTIONS]
+
+  Export the OpenAPI Specification to console or a file
+
+Options:
+  -o, --output PATH               The output file path.
+  -f, --format [json|yaml|markdown]
+                                  The output file format.
+  -i, --indent INTEGER            The indentation for JSON dumps.
+  -a, --ensure_ascii              Ensure ASCII characters or not. Defaults to
+                                  False.
+  --help                          Show this message and exit.
+
+```
+
+!!! info
+
+    You need to manually install `pyyaml` using pip:
+    ```bash
+    pip install flask-openapi3[yaml]
+    
+    # or
+    pip install pyyaml
+    ```
+
 ## doc_ui
 
 You can pass `doc_ui=False` to disable the `OpenAPI spec` when init `OpenAPI `.

docs/Quickstart.md

@@ -72,7 +72,7 @@ from flask_openapi3 import OpenAPI
 
 app = OpenAPI(__name__)
 
-api = APIBlueprint('/book', __name__, url_prefix='/api')
+api = APIBlueprint('book', __name__, url_prefix='/api')
 
 
 @api.post('/book')
@@ -86,3 +86,42 @@ 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](https://flask.palletsprojects.com/en/latest/blueprints/#nesting-blueprints).
+
+```python hl_lines="21 22"
+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)
+```
+

docs/Quickstart.zh.md

@@ -87,3 +87,42 @@ app.register_api(api)
 if __name__ == '__main__':
     app.run()
 ```
+
+## 嵌套 APIBlueprint
+
+*v2.0.0 新增*
+
+允许一个 **API Blueprint** 被另一个 **API Blueprint** 注册。
+
+更多信息请查看 [Flask Nesting Blueprints](https://flask.palletsprojects.com/en/latest/blueprints/#nesting-blueprints)。
+
+```python hl_lines="21 22"
+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)
+```
+

examples/nested_apiblueprint_demo.py

@@ -0,0 +1,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)

examples/response_demo.py

@@ -34,6 +34,16 @@ def hello(path: HelloPath):
     return response
 
 
+@bp.get("/hello_no_response/<string:name>", responses={"204": None})
+def hello_no_response(path: HelloPath):
+    message = {"message": f"""Hello {path.name}!"""}
+
+    # This message will never be returned because the http code (NO_CONTENT) doesn't return anything
+    response = make_response(message, HTTPStatus.NO_CONTENT)
+    response.mimetype = "application/json"
+    return response
+
+
 app.register_api(bp)
 
 if __name__ == "__main__":

flask_openapi3/__version__.py

@@ -2,4 +2,4 @@
 # @Author  : llc
 # @Time    : 2022/4/30 9:20
 
-__version__ = '1.1.4'
+__version__ = '2.0.0rc1'

flask_openapi3/api_blueprint.py

@@ -12,6 +12,7 @@
 from .do_wrapper import _do_wrapper
 from .http import HTTPMethod
 from .models import Tag, Components
+from .types import OpenAPIResponsesType
 from .utils import get_openapi_path, get_operation, get_responses, parse_and_store_tags, parse_parameters, \
     validate_responses_type, parse_method, get_operation_id_for_path
 
@@ -24,7 +25,7 @@ def __init__(
             *,
             abp_tags: Optional[List[Tag]] = None,
             abp_security: Optional[List[Dict[str, List[str]]]] = None,
-            abp_responses: Optional[Dict[str, Type[BaseModel]]] = None,
+            abp_responses: OpenAPIResponsesType = None,
             doc_ui: bool = True,
             **kwargs: Any
     ) -> None:
@@ -53,6 +54,28 @@ def __init__(
         self.abp_responses = abp_responses or {}
         self.doc_ui = doc_ui
 
+    def register_api(self, api: "APIBlueprint") -> None:
+        """Register a nested APIBlueprint"""
+        if api is self:
+            raise ValueError("Cannot register a api blueprint on itself")
+
+        for tag in api.tags:
+            if tag.name not in self.tag_names:
+                self.tags.append(tag)
+
+        for path_url, path_item in api.paths.items():
+            trail_slash = path_url.endswith('/')
+            # merge url_prefix and new api blueprint path url
+            uri = self.url_prefix.rstrip("/") + "/" + path_url.lstrip("/") if self.url_prefix else path_url
+            # strip the right slash
+            if not trail_slash:
+                uri = uri.rstrip('/')
+            self.paths[uri] = path_item
+
+        self.components_schemas.update(**api.components_schemas)
+
+        self.register_blueprint(api)
+
     def _do_decorator(
             self,
             rule: str,
@@ -145,12 +168,13 @@ def get(
             tags: Optional[List[Tag]] = None,
             summary: Optional[str] = None,
             description: Optional[str] = None,
-            responses: Optional[Dict[str, Type[BaseModel]]] = None,
+            responses: OpenAPIResponsesType = None,
             extra_responses: Optional[Dict[str, dict]] = None,
             security: Optional[List[Dict[str, List[Any]]]] = None,
             deprecated: Optional[bool] = None,
             operation_id: Optional[str] = None,
-            doc_ui: bool = True
+            doc_ui: bool = True,
+            **options: Any
     ) -> Callable:
         """Decorator for rest api, like: app.route(methods=['GET'])"""
 
@@ -186,7 +210,7 @@ def wrapper(**kwargs) -> Response:
                 )
                 return resp
 
-            options = {"methods": [HTTPMethod.GET]}
+            options.update({"methods": [HTTPMethod.GET]})
             self.add_url_rule(rule, view_func=wrapper, **options)
 
             return wrapper
@@ -200,12 +224,13 @@ def post(
             tags: Optional[List[Tag]] = None,
             summary: Optional[str] = None,
             description: Optional[str] = None,
-            responses: Optional[Dict[str, Type[BaseModel]]] = None,
+            responses: OpenAPIResponsesType = None,
             extra_responses: Optional[Dict[str, dict]] = None,
             security: Optional[List[Dict[str, List[Any]]]] = None,
             deprecated: Optional[bool] = None,
             operation_id: Optional[str] = None,
-            doc_ui: bool = True
+            doc_ui: bool = True,
+            **options: Any
     ) -> Callable:
         """Decorator for rest api, like: app.route(methods=['POST'])"""
 
@@ -241,7 +266,7 @@ def wrapper(**kwargs) -> Response:
                 )
                 return resp
 
-            options = {"methods": [HTTPMethod.POST]}
+            options.update({"methods": [HTTPMethod.POST]})
             self.add_url_rule(rule, view_func=wrapper, **options)
 
             return wrapper
@@ -255,12 +280,13 @@ def put(
             tags: Optional[List[Tag]] = None,
             summary: Optional[str] = None,
             description: Optional[str] = None,
-            responses: Optional[Dict[str, Type[BaseModel]]] = None,
+            responses: OpenAPIResponsesType = None,
             extra_responses: Optional[Dict[str, dict]] = None,
             security: Optional[List[Dict[str, List[Any]]]] = None,
             deprecated: Optional[bool] = None,
             operation_id: Optional[str] = None,
-            doc_ui: bool = True
+            doc_ui: bool = True,
+            **options: Any
     ) -> Callable:
         """Decorator for rest api, like: app.route(methods=['PUT'])"""
 
@@ -296,7 +322,7 @@ def wrapper(**kwargs) -> Response:
                 )
                 return resp
 
-            options = {"methods": [HTTPMethod.PUT]}
+            options.update({"methods": [HTTPMethod.PUT]})
             self.add_url_rule(rule, view_func=wrapper, **options)
 
             return wrapper
@@ -310,12 +336,13 @@ def delete(
             tags: Optional[List[Tag]] = None,
             summary: Optional[str] = None,
             description: Optional[str] = None,
-            responses: Optional[Dict[str, Type[BaseModel]]] = None,
+            responses: OpenAPIResponsesType = None,
             extra_responses: Optional[Dict[str, dict]] = None,
             security: Optional[List[Dict[str, List[Any]]]] = None,
             deprecated: Optional[bool] = None,
             operation_id: Optional[str] = None,
-            doc_ui: bool = True
+            doc_ui: bool = True,
+            **options: Any
     ) -> Callable:
         """Decorator for rest api, like: app.route(methods=['DELETE'])"""
 
@@ -351,7 +378,7 @@ def wrapper(**kwargs) -> Response:
                 )
                 return resp
 
-            options = {"methods": [HTTPMethod.DELETE]}
+            options.update({"methods": [HTTPMethod.DELETE]})
             self.add_url_rule(rule, view_func=wrapper, **options)
 
             return wrapper
@@ -365,12 +392,13 @@ def patch(
             tags: Optional[List[Tag]] = None,
             summary: Optional[str] = None,
             description: Optional[str] = None,
-            responses: Optional[Dict[str, Type[BaseModel]]] = None,
+            responses: OpenAPIResponsesType = None,
             extra_responses: Optional[Dict[str, dict]] = None,
             security: Optional[List[Dict[str, List[Any]]]] = None,
             deprecated: Optional[bool] = None,
             operation_id: Optional[str] = None,
-            doc_ui: bool = True
+            doc_ui: bool = True,
+            **options: Any
     ) -> Callable:
         """Decorator for rest api, like: app.route(methods=['PATCH'])"""
 
@@ -406,7 +434,7 @@ def wrapper(**kwargs) -> Response:
                 )
                 return resp
 
-            options = {"methods": [HTTPMethod.PATCH]}
+            options.update({"methods": [HTTPMethod.PATCH]})
             self.add_url_rule(rule, view_func=wrapper, **options)
 
             return wrapper