Merge pull request #76 from luolingchun/openapi_extra

Openapi extra
luolingchun · Jun 4, 2023 · 1c51e53 · 1c51e53
2 parents 035c127 + e3b928a
commit 1c51e53
Show file tree

Hide file tree

Showing 26 changed files with 860 additions and 373 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -2,5 +2,5 @@ Checklist:
 
 - [ ] Run `pytest tests` and no failed.
 - [ ] Run `flake8 flask_openapi3 tests examples` and no failed.
-- [ ] Run `mkdocs serve` and no failed.
 - [ ] Run `mypy flask_openapi3` and no failed.
+- [ ] Run `mkdocs serve` and no failed.
diff --git a/docs/Example.md b/docs/Example.md
@@ -127,8 +127,7 @@ class BookResponse(BaseModel):
     tags=[book_tag],
     summary='new summary',
     description='new description',
-    responses={"200": BookResponse},
-    extra_responses={"200": {"content": {"text/csv": {"schema": {"type": "string"}}}}},
+    responses={"200": BookResponse, "201": {"content": {"text/csv": {"schema": {"type": "string"}}}}},
     security=security
 )
 def get_book(path: BookPath):
@@ -189,7 +188,6 @@ from typing import Optional
 from pydantic import BaseModel, Field
 
 from flask_openapi3 import APIBlueprint, OpenAPI
-from flask_openapi3 import HTTPBearer
 from flask_openapi3 import Tag, Info
 
 info = Info(title='book API', version='1.0.0')
@@ -238,7 +236,7 @@ def get_book():
     return {"code": 0, "message": "ok"}
 
 
-@api.post('/book', extra_responses={"200": {"content": {"text/csv": {"schema": {"type": "string"}}}}})
+@api.post('/book', responses={"201": {"content": {"text/csv": {"schema": {"type": "string"}}}}})
 def create_book(body: BookBody):
     assert body.age == 3
     return {"code": 0, "message": "ok"}

diff --git a/docs/Tutorial/Openapi_extra.md b/docs/Tutorial/Openapi_extra.md
@@ -0,0 +1,105 @@
+*New in v2.4.0*
+
+The [BaseModel](https://docs.pydantic.dev/latest/usage/models/) in [Pydantic](https://github.com/pydantic/pydantic) 
+supports some custom configurations([Model Config](https://docs.pydantic.dev/latest/usage/model_config/)), 
+so we can use the `openapi_extra` to extend OpenAPI Specification.
+
+The `openapi_extra` will be merged with the automatically generated OpenAPI schema.
+
+## form
+
+```python
+class UploadFilesForm(BaseModel):
+    file: FileStorage
+    str_list: List[str]
+
+    class Config:
+        openapi_extra = {
+            # "example": {"a": 123},
+            "examples": {
+                "Example 01": {
+                    "summary": "An example",
+                    "value": {
+                        "file": "Example-01.jpg",
+                        "str_list": ["a", "b", "c"]
+                    }
+                },
+                "Example 02": {
+                    "summary": "Another example",
+                    "value": {
+                        "str_list": ["1", "2", "3"]
+                    }
+                }
+            }
+        }
+```
+
+Effect in Redoc:
+
+![](../assets/Snipaste_2023-06-02_11-05-11.png)
+
+## body
+
+```python
+class BookBody(BaseModel):
+    age: int
+    author: str
+
+    class Config:
+        openapi_extra = {
+            "description": "This is post RequestBody",
+            "example": {"age": 12, "author": "author1"},
+            "examples": {
+                "example1": {
+                    "summary": "example summary1",
+                    "description": "example description1",
+                    "value": {
+                        "age": 24,
+                        "author": "author2"
+                    }
+                },
+                "example2": {
+                    "summary": "example summary2",
+                    "description": "example description2",
+                    "value": {
+                        "age": 48,
+                        "author": "author3"
+                    }
+                }
+
+            }}
+```
+
+Effect in swagger:
+
+![](../assets/Snipaste_2023-06-02_11-06-59.png)
+
+## responses
+
+```python
+class Message(BaseModel):
+    message: str = Field(..., description="The message")
+
+    class Config:
+        openapi_extra = {
+            # "example": {"message": "aaa"},
+            "examples": {
+                "example1": {
+                    "summary": "example1 summary",
+                    "value": {
+                        "message": "bbb"
+                    }
+                },
+                "example2": {
+                    "summary": "example2 summary",
+                    "value": {
+                        "message": "ccc"
+                    }
+                }
+            }
+        }
+```
+
+Effect in swagger:
+
+![](../assets/Snipaste_2023-06-02_11-08-40.png)
diff --git a/docs/Tutorial/Operation.md b/docs/Tutorial/Operation.md
@@ -127,6 +127,12 @@ def create_book(body: BookBody):
 
 ## extra_form
 
+*new in v2.4.0*
+
+!!! Deprecated-Warning warning
+
+    `extra_form` will be deprecated in v3.x, please use `openapi_extra` instead.
+
 *new in v2.1.0*
 
 Extra form information can be provided using `extra_form` as in the following sample:
@@ -148,6 +154,12 @@ def create_book(body: BookForm):
 
 ## extra_body
 
+*new in v2.4.0*
+
+!!! Deprecated-Warning warning
+
+    `extra_body` will be deprecated in v3.x, please use `openapi_extra` instead.
+
 *new in v2.1.0*
 
 Extra body information can be provided using `extra_body` as in the following sample:

diff --git a/docs/Tutorial/Response.md b/docs/Tutorial/Response.md
@@ -15,7 +15,13 @@ class BookResponse(BaseModel):
     data: BookBodyWithID
 
 
-@app.get('/book/<int:bid>', tags=[book_tag], responses={"200": BookResponse})
+@app.get('/book/<int:bid>', 
+         tags=[book_tag], 
+         responses={
+             "200": BookResponse, 
+             # Version 2.4.0 starts supporting response for dictionary types
+             "201": {"content": {"text/csv": {"schema": {"type": "string"}}}}
+         })
 def get_book(path: BookPath, query: BookBody):
     """get a book
     get book by id, age or author
@@ -26,9 +32,14 @@ def get_book(path: BookPath, query: BookBody):
 
 ![image-20210526104627124](../assets/image-20210526104627124.png)
 
-
 ## extra_responses
 
+*New in v2.4.0*
+
+!!! Deprecated-Warning warning
+
+    `extra_responses` have been merged into the `responses`, and `extra_responses` will be deprecated in v3.x.
+
 *New in v1.0.0*
 
 You can pass to your path operation decorators a parameter `extra_responses`.
@@ -43,14 +54,14 @@ Like this:
     '/book/<int:bid>',
     tags=[book_tag],
     responses={"200": BookResponse},
-    extra_responses={"200": {"content": {"text/csv": {"schema": {"type": "string"}}}}},
+    extra_responses={"201": {"content": {"text/csv": {"schema": {"type": "string"}}}}},
     security=security
 )
 def get_book(path: BookPath):
     ...
 
 
-@api.post('/book', extra_responses={"200": {"content": {"text/csv": {"schema": {"type": "string"}}}}})
+@api.post('/book', extra_responses={"201": {"content": {"text/csv": {"schema": {"type": "string"}}}}})
 def create_book(body: BookBody):
     ...
 ```

diff --git a/docs/Tutorial/Specification.md b/docs/Tutorial/Specification.md
@@ -252,6 +252,14 @@ def endpoint():
 
 You can also use [responses ](./Response.md#responses) and [extra_responses](./Response.md#extra_responses) in your api.
 
+*New in v2.4.0*
+
+!!! Deprecated-Warning warning
+
+    `extra_responses` have been merged into the `responses`, and `extra_responses` will be deprecated in v3.x.
+
+
+
 ## doc_ui
 
 You can pass `doc_ui=False` to disable the `OpenAPI spec` when init `OpenAPI `.

diff --git a/docs/assets/Snipaste_2023-06-02_11-05-11.png b/docs/assets/Snipaste_2023-06-02_11-05-11.png
diff --git a/docs/assets/Snipaste_2023-06-02_11-06-59.png b/docs/assets/Snipaste_2023-06-02_11-06-59.png
diff --git a/docs/assets/Snipaste_2023-06-02_11-08-40.png b/docs/assets/Snipaste_2023-06-02_11-08-40.png
diff --git a/examples/api_blueprint_demo.py b/examples/api_blueprint_demo.py
@@ -55,7 +55,7 @@ def get_book():
     return {"code": 0, "message": "ok"}
 
 
-@api.post('/book', extra_responses={"200": {"content": {"text/csv": {"schema": {"type": "string"}}}}})
+@api.post('/book', responses={"200": {"content": {"text/csv": {"schema": {"type": "string"}}}}})
 def create_book(body: BookBody):
     assert body.age == 3
     return {"code": 0, "message": "ok"}

diff --git a/examples/openapi_extra.py b/examples/openapi_extra.py
@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/6/1 15:04
+from typing import List
+
+from pydantic import BaseModel
+
+from flask_openapi3 import OpenAPI, FileStorage
+
+app = OpenAPI(__name__)
+
+
+class UploadFilesForm(BaseModel):
+    file: FileStorage
+    str_list: List[str]
+
+    class Config:
+        openapi_extra = {
+            # "example": {"a": 123},
+            "examples": {
+                "Example 01": {
+                    "summary": "An example",
+                    "value": {
+                        "file": "Example-01.jpg",
+                        "str_list": ["a", "b", "c"]
+                    }
+                },
+                "Example 02": {
+                    "summary": "Another example",
+                    "value": {
+                        "str_list": ["1", "2", "3"]
+                    }
+                }
+            }
+        }
+
+
+class BookBody(BaseModel):
+    age: int
+    author: str
+
+    class Config:
+        openapi_extra = {
+            "description": "This is post RequestBody",
+            "example": {"age": 12, "author": "author1"},
+            "examples": {
+                "example1": {
+                    "summary": "example summary1",
+                    "description": "example description1",
+                    "value": {
+                        "age": 24,
+                        "author": "author2"
+                    }
+                },
+                "example2": {
+                    "summary": "example summary2",
+                    "description": "example description2",
+                    "value": {
+                        "age": 48,
+                        "author": "author3"
+                    }
+                }
+
+            }}
+
+
+@app.post('/upload/files')
+def upload_files(form: UploadFilesForm):
+    print(form.file)
+    print(form.str_list)
+    return {"code": 0, "message": "ok"}
+
+
+@app.post('/book', )
+def create_book(body: BookBody):
+    print(body)
+    return {"code": 0, "message": "ok"}
+
+
+if __name__ == "__main__":
+    app.run(debug=True)
diff --git a/examples/response_demo.py b/examples/response_demo.py
@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# @Author  : [martinatseequent](https://github.com/martinatseequent)
+# @Author  : llc
 # @Time    : 2021/6/22 9:32
 
 import json
@@ -11,7 +11,7 @@
 from flask_openapi3 import Info
 from flask_openapi3 import OpenAPI, APIBlueprint
 
-app = OpenAPI(__name__, info=Info(title="Hello API", version="1.0.0"), )
+app = OpenAPI(__name__, info=Info(title="Hello API", version="1.0.0"))
 
 bp = APIBlueprint("Hello BP", __name__)
 
@@ -23,8 +23,28 @@ class HelloPath(BaseModel):
 class Message(BaseModel):
     message: str = Field(..., description="The message")
 
-
-@bp.get("/hello/<string:name>", responses={"200": Message})
+    class Config:
+        openapi_extra = {
+            # "example": {"message": "aaa"},
+            "examples": {
+                "example1": {
+                    "summary": "example1 summary",
+                    "value": {
+                        "message": "bbb"
+                    }
+                },
+                "example2": {
+                    "summary": "example2 summary",
+                    "value": {
+                        "message": "ccc"
+                    }
+                }
+            }
+        }
+
+
+@bp.get("/hello/<string:name>",
+        responses={"200": Message, "201": {"content": {"text/csv": {"schema": {"type": "string"}}}}})
 def hello(path: HelloPath):
     message = {"message": f"""Hello {path.name}!"""}