Merge pull request #76 from luolingchun/openapi_extra

Openapi extra

Author: luolingchun

.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.

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"}

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)

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:

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):
     ...
 ```

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 `.

docs/assets/Snipaste_2023-06-02_11-05-11.png

@@ -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"}