Skip to content

Commit

Permalink
📝 Update documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
Raphael Krupinski committed Jan 9, 2024
1 parent 1940bfd commit 7f9903d
Showing 1 changed file with 14 additions and 11 deletions.
25 changes: 14 additions & 11 deletions docs/python_representation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Python code representation of OpenAPI document

The goal of python representation is to allow python code to fully replace OpanAPI document, allow Lapidary library to prepare a HTTP request and parse the response, in a way compatible with the server describe by that OpenAPI document.
The goal of python representation is to allow python code to fully replace OpanAPI document, allow Lapidary library to prepare a HTTP request and parse the response, in a way compatible with the
server describe by that OpenAPI document.

The python representation must be fully sufficient, must not require the original document to function, and usage must execute a valid exchange with a server.

Expand Down Expand Up @@ -32,24 +33,26 @@ The possible work-arounds are:
Lapidary uses annotations, which declares parameter location and may be used to provide the name.

```python
from typing import Annotated
from lapidary.runtime.model.params import CookieParam


async def operation(
self,
param1_c: Annotated[str, CookieParam('param1')],
):
...
from typing import Annotated, Self
from lapidary.runtime import Cookie, ClientBase

class Client(ClientBase):
async def operation(
self: Self,
*,
param1_c: Annotated[str, Cookie('param1')],
):
pass
```

#### Serialization

Serialization in OpenAPI is a rather complex subject, and not well defined.
Serialization in OpenAPI is a rather complex subject, and not always defined well.

An example of undefined behaviour is serialization of nested object with simple or form style, which is neither defined nor forbidden.

Possible solution are:

- explicitly forbidding certain cases
- extending the specification, and optionally accepting extra parameters (i.e. field delimiter in nested objects)
- accepting custom de/serialization function
Expand Down

0 comments on commit 7f9903d

Please sign in to comment.