From 53629516e20b03fc369bfdbe500b44404a9a740f Mon Sep 17 00:00:00 2001
From: Raphael Krupinski <10319569-mattesilver@users.noreply.gitlab.com>
Date: Tue, 6 Feb 2024 15:48:50 +0100
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Move=20OpenAPI=20representation?=
 =?UTF-8?q?=20to=20a=20separate=20repo.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 config/mkdocs.yml            |  3 --
 docs/openapi/index.md        | 75 ------------------------------------
 docs/openapi/request_body.md | 14 -------
 3 files changed, 92 deletions(-)
 delete mode 100644 docs/openapi/index.md
 delete mode 100644 docs/openapi/request_body.md

diff --git a/config/mkdocs.yml b/config/mkdocs.yml
index 0376535..01e4cf5 100644
--- a/config/mkdocs.yml
+++ b/config/mkdocs.yml
@@ -15,9 +15,6 @@ nav:
   - usage/client.md
   - usage/operation.md
   - usage/auth.md
-- OpenAPI:
-  - openapi/index.md
-  - openapi/request_body.md
 
 plugins:
 - mkdocstrings:
diff --git a/docs/openapi/index.md b/docs/openapi/index.md
deleted file mode 100644
index 54f1b64..0000000
--- a/docs/openapi/index.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# Representing OpenAPI
-
-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 described by that representation.
-
-The python representation is fully self-sufficient, and doesn't require an OpenAPI document at runtime.
-
-## Client
-
-A client to a remote service may be represented as a collection of functions, each representing an operation, and a collection of data classes, each representing a schema.
-The functions could be module-level or grouped in one or more classes, optionally forming an object hierarchy.
-
-Lapidary currently implements a single class approach.
-
-## Paths and Operations
-
-OpenAPI `paths` object can be explained as a mapping of HTTP method and path to an Operation declaration.
-
-OpenAPI Operation specifies the request body, parameters and responses, so it's the closest thing to a python function.
-
-### Parameters
-
-#### Naming
-
-Each of cookie, header, path and query parameters have their own namespace, so they can't be directly mapped to names of parameters of a python function.
-
-The possible workarounds are:
-
-- grouping parameters in mappings, named tuples or objects,
-- name mangling,
-- annotations.
-
-Lapidary uses annotations, which declares parameter location and may be used to provide the name.
-
-```python
-from typing import Annotated, Self
-from lapidary.runtime import Cookie, ClientBase, Header
-
-class Client(ClientBase):
-    async def operation(
-        self: Self,
-        *,
-        param1_c: Annotated[str, Cookie('param1')],
-        param1_h: Annotated[str, Header('param1')],
-    ):
-        pass
-```
-
-#### Serialization
-
-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
-
-### Request Body
-
-See [Request body](request_body.md)
-
-### Responses
-
-TODO
-
-## Auth
-
-See [Auth](../usage//auth.md).
-
-## Servers
-
-TODO
diff --git a/docs/openapi/request_body.md b/docs/openapi/request_body.md
deleted file mode 100644
index 1a74a52..0000000
--- a/docs/openapi/request_body.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Request body
-
-## OpenAPI
-
-OpenAPI 3.x defines the request object as a mapping of media type (or media type range, e.g. 'application/*') to encoding, schema and headers.
-
-This means that the server accepts one or more data types under various media types.
-
-On the client side we have the type as the input, which means we need to reverse the mapping, and in result we may end up with multiple media types or a media type range
-but we need to send a single specific `Content-Type` header.
-
-## Python
-
-For such cases a `Header('Content-Type')` parameter can be used, and in such cases it should be required.