Support multi content type in request body and responses

Author: luolingchun

docs/Usage/Request.md

@@ -167,6 +167,88 @@ def get_book(query: BookQuery, client_id:str = None):
  ...
 ```
 
+## Multiple content types in the request body
+
+```python
+from typing import Union
+
+from flask import Request
+from pydantic import BaseModel
+
+from flask_openapi3 import OpenAPI
+
+app = OpenAPI(__name__)
+
+
+class DogBody(BaseModel):
+ a: int = None
+ b: str = None
+
+ model_config = {
+ "openapi_extra": {
+ "content_type": "application/vnd.dog+json"
+ }
+ }
+
+
+class CatBody(BaseModel):
+ c: int = None
+ d: str = None
+
+ model_config = {
+ "openapi_extra": {
+ "content_type": "application/vnd.cat+json"
+ }
+ }
+
+
+class BsonModel(BaseModel):
+ e: int = None
+ f: str = None
+
+ model_config = {
+ "openapi_extra": {
+ "content_type": "application/bson"
+ }
+ }
+
+
+class ContentTypeModel(BaseModel):
+ model_config = {
+ "openapi_extra": {
+ "content_type": "text/csv"
+ }
+ }
+
+
+@app.post("/a", responses={200: DogBody | CatBody | ContentTypeModel | BsonModel})
+def index_a(body: DogBody | CatBody | ContentTypeModel | BsonModel):
+ """
+ multiple content types examples.
+
+ This may be confusing, if the content-type is application/json, the type of body will be auto parsed to
+ DogBody or CatBody, otherwise it cannot be parsed to ContentTypeModel or BsonModel.
+ The body is equivalent to the request variable in Flask, and you can use body.data, body.text, etc ...
+ """
+ print(body)
+ if isinstance(body, Request):
+ if body.mimetype == "text/csv":
+ # processing csv data
+ ...
+ elif body.mimetype == "application/bson":
+ # processing bson data
+ ...
+ else:
+ # DogBody or CatBody
+ ...
+ return {"hello": "world"}
+```
+
+The effect in swagger:
+
+![](../assets/Snipaste_2025-01-14_10-44-00.png)
+
+
 ## Request model
 
 First, you need to define a [pydantic](https://github.com/pydantic/pydantic) model:
@@ -191,7 +273,7 @@ class BookQuery(BaseModel):
  author: str = Field(None, description='Author', json_schema_extra={"deprecated": True})
 ```
 
-Magic:
+The effect in swagger:
 
 ![](../assets/Snipaste_2022-09-04_10-10-03.png)
 

docs/Usage/Response.md

@@ -56,6 +56,122 @@ def hello(path: HelloPath):
 
 ![image-20210526104627124](../assets/image-20210526104627124.png)
 
+*Sometimes you may need more description fields about the response, such as description, headers and links.
+
+You can use the following form:
+
+```python
+@app.get(
+ "/test",
+ responses={
+ "201": {
+ "model": BaseResponse,
+ "description": "Custom description",
+ "headers": {
+ "location": {
+ "description": "URL of the new resource",
+ "schema": {"type": "string"}
+ }
+ },
+ "links": {
+ "dummy": {
+ "description": "dummy link"
+ }
+ }
+ }
+ }
+ )
+ def endpoint_test():
+ ...
+```
+
+The effect in swagger:
+
+![](../assets/Snipaste_2025-01-14_11-08-40.png)
+
+
+## Multiple content types in the responses
+
+```python
+from typing import Union
+
+from flask import Request
+from pydantic import BaseModel
+
+from flask_openapi3 import OpenAPI
+
+app = OpenAPI(__name__)
+
+
+class DogBody(BaseModel):
+ a: int = None
+ b: str = None
+
+ model_config = {
+ "openapi_extra": {
+ "content_type": "application/vnd.dog+json"
+ }
+ }
+
+
+class CatBody(BaseModel):
+ c: int = None
+ d: str = None
+
+ model_config = {
+ "openapi_extra": {
+ "content_type": "application/vnd.cat+json"
+ }
+ }
+
+
+class BsonModel(BaseModel):
+ e: int = None
+ f: str = None
+
+ model_config = {
+ "openapi_extra": {
+ "content_type": "application/bson"
+ }
+ }
+
+
+class ContentTypeModel(BaseModel):
+ model_config = {
+ "openapi_extra": {
+ "content_type": "text/csv"
+ }
+ }
+
+
+@app.post("/a", responses={200: DogBody | CatBody | ContentTypeModel | BsonModel})
+def index_a(body: DogBody | CatBody | ContentTypeModel | BsonModel):
+ """
+ multiple content types examples.
+
+ This may be confusing, if the content-type is application/json, the type of body will be auto parsed to
+ DogBody or CatBody, otherwise it cannot be parsed to ContentTypeModel or BsonModel.
+ The body is equivalent to the request variable in Flask, and you can use body.data, body.text, etc ...
+ """
+ print(body)
+ if isinstance(body, Request):
+ if body.mimetype == "text/csv":
+ # processing csv data
+ ...
+ elif body.mimetype == "application/bson":
+ # processing bson data
+ ...
+ else:
+ # DogBody or CatBody
+ ...
+ return {"hello": "world"}
+```
+
+The effect in swagger:
+
+![](../assets/Snipaste_2025-01-14_10-49-19.png)
+
+
 ## More information about OpenAPI responses
 
 - [OpenAPI Responses Object](https://spec.openapis.org/oas/v3.1.0#responses-object), it includes the Response Object.

docs/Usage/Route_Operation.md

@@ -289,6 +289,29 @@ class BookListAPIView:
 app.register_api_view(api_view)
 ```
 
+## request_body_description
+
+A brief description of the request body.
+
+```python
+from flask_openapi3 import OpenAPI
+
+app = OpenAPI(__name__)
+
+@app.post(
+ "/",
+ request_body_description="A brief description of the request body."
+)
+def create_book(body: Bookbody):
+ ...
+```
+
+![](../assets/Snipaste_2025-01-14_10-56-40.png)
+
+## request_body_required
+
+Determines if the request body is required in the request.
+
 ## doc_ui
 
 You can pass `doc_ui=False` to disable the `OpenAPI spec` when init `OpenAPI `.

docs/assets/Snipaste_2025-01-14_10-44-00.png

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+# @Author : llc
+# @Time : 2024/12/27 15:30
+from flask import Request
+from pydantic import BaseModel
+
+from flask_openapi3 import OpenAPI
+
+app = OpenAPI(__name__)
+
+
+class DogBody(BaseModel):
+ a: int = None
+ b: str = None
+
+ model_config = {"openapi_extra": {"content_type": "application/vnd.dog+json"}}
+
+
+class CatBody(BaseModel):
+ c: int = None
+ d: str = None
+
+ model_config = {"openapi_extra": {"content_type": "application/vnd.cat+json"}}
+
+
+class BsonModel(BaseModel):
+ e: int = None
+ f: str = None
+
+ model_config = {"openapi_extra": {"content_type": "application/bson"}}
+
+
+class ContentTypeModel(BaseModel):
+ model_config = {"openapi_extra": {"content_type": "text/csv"}}
+
+
+@app.post("/a", responses={200: DogBody | CatBody | ContentTypeModel | BsonModel})
+def index_a(body: DogBody | CatBody | ContentTypeModel | BsonModel):
+ """
+ multiple content types examples.
+
+ This may be confusing, if the content-type is application/json, the type of body will be auto parsed to
+ DogBody or CatBody, otherwise it cannot be parsed to ContentTypeModel or BsonModel.
+ The body is equivalent to the request variable in Flask, and you can use body.data, body.text, etc ...
+ """
+ print(body)
+ if isinstance(body, Request):
+ if body.mimetype == "text/csv":
+ # processing csv data
+ ...
+ elif body.mimetype == "application/bson":
+ # processing bson data
+ from bson import BSON
+
+ obj = BSON(body.data).decode()
+ new_body = body.model_validate(obj=obj)
+ print(new_body)
+ else:
+ # DogBody or CatBody
+ ...
+ return {"hello": "world"}
+
+
+if __name__ == "__main__":
+ app.run(debug=True)

docs/assets/Snipaste_2025-01-14_10-49-19.png

@@ -121,6 +121,8 @@ def _collect_openapi_info(
  security: list[dict[str, list[Any]]] | None = None,
  servers: list[Server] | None = None,
  openapi_extensions: dict[str, Any] | None = None,
+ request_body_description: str | None = None,
+ request_body_required: bool | None = True,
  doc_ui: bool = True,
  method: str = HTTPMethod.GET,
  ) -> ParametersTuple:
@@ -140,6 +142,8 @@ def _collect_openapi_info(
  security: A declaration of which security mechanisms can be used for this operation.
  servers: An alternative server array to service this operation.
  openapi_extensions: Allows extensions to the OpenAPI Schema.
+ request_body_description: A brief description of the request body.
+ request_body_required: Determines if the request body is required in the request.
  doc_ui: Declares this operation to be shown. Default to True.
  """
  if self.doc_ui is True and doc_ui is True:
@@ -191,6 +195,12 @@ def _collect_openapi_info(
  parse_method(uri, method, self.paths, operation)
 
  # Parse parameters
- return parse_parameters(func, components_schemas=self.components_schemas, operation=operation)
+ return parse_parameters(
+ func,
+ components_schemas=self.components_schemas,
+ operation=operation,
+ request_body_description=request_body_description,
+ request_body_required=request_body_required,
+ )
  else:
  return parse_parameters(func, doc_ui=False)

docs/assets/Snipaste_2025-01-14_10-56-40.png

@@ -9,8 +9,6 @@
 https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#table-of-contents
 """
 
-from typing import Optional, Union
-
 from flask import Request
 from pydantic import BaseModel