chore: Document & test changes

Author: dbanty

.changeset/always_use_correct_content_type_for_requests.md

@@ -0,0 +1,9 @@
+---
+default: patch
+---
+
+# Always use correct content type for requests
+
+In previous versions, a request body that was similar to a known content type would use that content type in the request. For example `application/json` would be used for `application/vnd.api+json`. This was incorrect and could result in invalid requests being sent.
+
+Now, the content type defined in the OpenAPI document will always be used.

.changeset/renamed_body_types_and_parameters.md

@@ -0,0 +1,29 @@
+---
+default: major
+---
+
+# Renamed body types and parameters
+
+PR #900 addresses #822.
+
+Where previously there would be one body parameter per supported content type, now there is a single `body` parameter which takes a union of all the possible inputs. This correctly models the fact that only one body can be sent (and ever would be sent) in a request.
+
+For example, when calling a generated endpoint, code which used to look like this:
+
+```python
+post_body_multipart.sync_detailed(
+    client=client,
+    multipart_data=PostBodyMultipartMultipartData(),
+)
+```
+
+Will now look like this:
+
+```python
+post_body_multipart.sync_detailed(
+    client=client,
+    body=PostBodyMultipartBody(),
+)
+```
+
+Note that both the input parameter name _and_ the class name have changed. This should result in simpler code when there is only a single body type and now produces correct code when there are multiple body types.

.changeset/support_multiple_possible_requestbody.md

@@ -0,0 +1,16 @@
+---
+default: minor
+---
+
+# Support multiple possible `requestBody`
+
+PR #900 addresses #822.
+
+It is now possible in some circumstances to generate valid code for OpenAPI documents which have multiple possible `requestBody` values. Previously, invalid code could have been generated with no warning (only one body could actually be sent).
+
+Only one content type per "category" is currently supported at a time. The categories are:
+
+- JSON, like `application/json`
+- Binary data, like `application/octet-stream`
+- Encoded form data, like `application/x-www-form-urlencoded`
+- Files, like `multipart/form-data`

end_to_end_tests/custom-templates-golden-record/my_test_api_client/api/__init__.py

@@ -2,6 +2,7 @@
 
 from typing import Type
 
+from .bodies import BodiesEndpoints
 from .default import DefaultEndpoints
 from .location import LocationEndpoints
 from .naming import NamingEndpoints
@@ -14,6 +15,10 @@
 
 
 class MyTestApiClientApi:
+    @classmethod
+    def bodies(cls) -> Type[BodiesEndpoints]:
+        return BodiesEndpoints
+
     @classmethod
     def tests(cls) -> Type[TestsEndpoints]:
         return TestsEndpoints

end_to_end_tests/custom-templates-golden-record/my_test_api_client/api/bodies/__init__.py

@@ -0,0 +1,21 @@
+""" Contains methods for accessing the API Endpoints """
+
+import types
+
+from . import json_like, post_bodies_multiple
+
+
+class BodiesEndpoints:
+    @classmethod
+    def post_bodies_multiple(cls) -> types.ModuleType:
+        """
+        Test multiple bodies
+        """
+        return post_bodies_multiple
+
+    @classmethod
+    def json_like(cls) -> types.ModuleType:
+        """
+        A content type that works like json but isn't application/json
+        """
+        return json_like

end_to_end_tests/golden-record/my_test_api_client/api/bodies/__init__.py

@@ -0,0 +1,103 @@
+from http import HTTPStatus
+from typing import Any, Dict, Optional, Union
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.json_like_body import JsonLikeBody
+from ...types import Response
+
+
+def _get_kwargs(
+    *,
+    body: JsonLikeBody,
+) -> Dict[str, Any]:
+    headers = {}
+
+    _kwargs: Dict[str, Any] = {
+        "method": "post",
+        "url": "/bodies/json-like",
+    }
+
+    _body = body.to_dict()
+
+    _kwargs["json"] = _body
+    headers["Content-Type"] = "application/vnd+json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(*, client: Union[AuthenticatedClient, Client], response: httpx.Response) -> Optional[Any]:
+    if response.status_code == HTTPStatus.OK:
+        return None
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(*, client: Union[AuthenticatedClient, Client], response: httpx.Response) -> Response[Any]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: Union[AuthenticatedClient, Client],
+    body: JsonLikeBody,
+) -> Response[Any]:
+    """A content type that works like json but isn't application/json
+
+    Args:
+        body (JsonLikeBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Any]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio_detailed(
+    *,
+    client: Union[AuthenticatedClient, Client],
+    body: JsonLikeBody,
+) -> Response[Any]:
+    """A content type that works like json but isn't application/json
+
+    Args:
+        body (JsonLikeBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Any]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)

end_to_end_tests/golden-record/my_test_api_client/api/bodies/json_like.py

@@ -0,0 +1,142 @@
+from http import HTTPStatus
+from typing import Any, Dict, Optional, Union
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.post_bodies_multiple_data_body import PostBodiesMultipleDataBody
+from ...models.post_bodies_multiple_files_body import PostBodiesMultipleFilesBody
+from ...models.post_bodies_multiple_json_body import PostBodiesMultipleJsonBody
+from ...types import File, Response
+
+
+def _get_kwargs(
+    *,
+    body: Union[
+        PostBodiesMultipleJsonBody,
+        File,
+        PostBodiesMultipleDataBody,
+        PostBodiesMultipleFilesBody,
+    ],
+) -> Dict[str, Any]:
+    headers = {}
+
+    _kwargs: Dict[str, Any] = {
+        "method": "post",
+        "url": "/bodies/multiple",
+    }
+
+    if isinstance(body, PostBodiesMultipleJsonBody):
+        _json_body = body.to_dict()
+
+        _kwargs["json"] = _json_body
+        headers["Content-Type"] = "application/json"
+    if isinstance(body, File):
+        _content_body = body.payload
+
+        _kwargs["content"] = _content_body
+        headers["Content-Type"] = "application/octet-stream"
+    if isinstance(body, PostBodiesMultipleDataBody):
+        _data_body = body.to_dict()
+
+        _kwargs["data"] = _data_body
+        headers["Content-Type"] = "application/x-www-form-urlencoded"
+    if isinstance(body, PostBodiesMultipleFilesBody):
+        _files_body = body.to_multipart()
+
+        _kwargs["files"] = _files_body
+        headers["Content-Type"] = "multipart/form-data"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(*, client: Union[AuthenticatedClient, Client], response: httpx.Response) -> Optional[Any]:
+    if response.status_code == HTTPStatus.OK:
+        return None
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(*, client: Union[AuthenticatedClient, Client], response: httpx.Response) -> Response[Any]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: Union[AuthenticatedClient, Client],
+    body: Union[
+        PostBodiesMultipleJsonBody,
+        File,
+        PostBodiesMultipleDataBody,
+        PostBodiesMultipleFilesBody,
+    ],
+) -> Response[Any]:
+    """Test multiple bodies
+
+    Args:
+        body (PostBodiesMultipleJsonBody):
+        body (File):
+        body (PostBodiesMultipleDataBody):
+        body (PostBodiesMultipleFilesBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Any]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio_detailed(
+    *,
+    client: Union[AuthenticatedClient, Client],
+    body: Union[
+        PostBodiesMultipleJsonBody,
+        File,
+        PostBodiesMultipleDataBody,
+        PostBodiesMultipleFilesBody,
+    ],
+) -> Response[Any]:
+    """Test multiple bodies
+
+    Args:
+        body (PostBodiesMultipleJsonBody):
+        body (File):
+        body (PostBodiesMultipleDataBody):
+        body (PostBodiesMultipleFilesBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Any]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)

end_to_end_tests/golden-record/my_test_api_client/api/bodies/post_bodies_multiple.py

@@ -37,6 +37,7 @@
 from .get_location_header_types_string_enum_header import GetLocationHeaderTypesStringEnumHeader
 from .http_validation_error import HTTPValidationError
 from .import_ import Import
+from .json_like_body import JsonLikeBody
 from .model_from_all_of import ModelFromAllOf
 from .model_name import ModelName
 from .model_reference_with_periods import ModelReferenceWithPeriods
@@ -63,6 +64,9 @@
 from .model_with_union_property_inlined_fruit_type_0 import ModelWithUnionPropertyInlinedFruitType0
 from .model_with_union_property_inlined_fruit_type_1 import ModelWithUnionPropertyInlinedFruitType1
 from .none import None_
+from .post_bodies_multiple_data_body import PostBodiesMultipleDataBody
+from .post_bodies_multiple_files_body import PostBodiesMultipleFilesBody
+from .post_bodies_multiple_json_body import PostBodiesMultipleJsonBody
 from .post_form_data_inline_body import PostFormDataInlineBody
 from .post_naming_property_conflict_with_import_body import PostNamingPropertyConflictWithImportBody
 from .post_naming_property_conflict_with_import_response_200 import PostNamingPropertyConflictWithImportResponse200
@@ -106,6 +110,7 @@
     "GetLocationHeaderTypesStringEnumHeader",
     "HTTPValidationError",
     "Import",
+    "JsonLikeBody",
     "ModelFromAllOf",
     "ModelName",
     "ModelReferenceWithPeriods",
@@ -130,6 +135,9 @@
     "ModelWithUnionPropertyInlinedFruitType0",
     "ModelWithUnionPropertyInlinedFruitType1",
     "None_",
+    "PostBodiesMultipleDataBody",
+    "PostBodiesMultipleFilesBody",
+    "PostBodiesMultipleJsonBody",
     "PostFormDataInlineBody",
     "PostNamingPropertyConflictWithImportBody",
     "PostNamingPropertyConflictWithImportResponse200",