Update doc for Openapi Extra

luolingchun · Jun 2, 2023 · b2910e4 · b2910e4
1 parent 7d41436
commit b2910e4
Show file tree

Hide file tree

Showing 12 changed files with 152 additions and 10 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/flask_openapi3/models/common.py b/flask_openapi3/models/common.py
@@ -1,10 +1,13 @@
 # -*- coding: utf-8 -*-
 # @Author  : llc
 # @Time    : 2021/4/30 11:46
+import warnings
 from typing import Optional, List, Any, Union, Dict
 
 from pydantic import BaseModel, Field
 
+warnings.simplefilter("once")
+
 
 class ExternalDocumentation(BaseModel):
     description: Optional[str] = None
@@ -129,3 +132,7 @@ class ExtraRequestBody(BaseModel):
     example: Optional[Any] = None
     examples: Optional[Dict[str, Union[Example, Reference]]] = None
     encoding: Optional[Dict[str, Encoding]] = None
+
+    def __new__(cls, *args, **kwargs):
+        warnings.warn(f"""\n{cls.__name__} will be deprecated in v3.x.""", DeprecationWarning)
+        return super().__new__(cls)
diff --git a/flask_openapi3/utils.py b/flask_openapi3/utils.py
@@ -314,7 +314,7 @@ def get_responses(
                 _content["application/json"].examples = model_config.openapi_extra.get("examples")  # type: ignore
                 _content["application/json"].encoding = model_config.openapi_extra.get("encoding")  # type: ignore
                 if model_config.openapi_extra.get("content"):
-                    _responses[key].content.update(model_config.openapi_extra.get("content"))
+                    _responses[key].content.update(model_config.openapi_extra.get("content"))  # type: ignore
 
             _schemas[response.__name__] = Schema(**schema)
             definitions = schema.get("definitions")

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -89,6 +89,7 @@ nav:
       - Operation: Tutorial/Operation.md
       - Request: Tutorial/Request.md
       - Response: Tutorial/Response.md
+      - OpenAPI Extra: Tutorial/Openapi_extra.md
       - UI Templates: Tutorial/UI_Templates.md
       - JSON: Tutorial/JSON.md
   - Example: Example.md