📝 Document compatibility with OpenAPI. Extend dummy OpenAPI doc with examples.

Author: rafalkrupinski

config/mkdocs.yml

@@ -5,3 +5,4 @@ docs_dir: ../docs
 
 nav:
 - index.md
+- openapi.md

docs/openapi.md

@@ -0,0 +1,75 @@
+# OpenAPI compatibility
+
+- openapi: validated (3.0.* accepted)
+- info
+    - license: Not usable. It's up to the user to verify the accepted use.
+    - title and other fields: planned as part of project readme
+- externalDocs: planned as part of the project readme
+- servers: first server is used
+    - url: used as the base URL
+    - variables: default values are used to evaluate the server URL
+- security: implemented
+- tags: ignored, not planned
+- components
+    - schemas:
+        - title: planned as part of class docstr
+        - type
+            - [no value]: planned as primitive JSON-compatible object.
+            - object: implemented as pydantic models
+            - array: implemented as list
+            - string, integer, number, boolean: implemented as str, int, float and bool
+        - format: planned, including custom formats
+        - validation keyword: supported by pydantic
+        - allOf: needs improvement
+        - oneOf and anyOf: implemented as union
+        - not: planned for objects
+        - required: non-required properties are turned to `Union[None, $type]`
+        - additionalProperties:
+            - boolean: supported as pydantic `extra: 'allow'` or `'forbid'`
+            - schema: planned as a `Mapping` field
+        - patternProperties: planned as `Mapping` field
+        - enum: ignored; might be implemented for simple types as `Literal`
+        - description: planned as part of docstr
+        - default: if present, the property type turned to `Union[None, $type]` and has default value `None`
+            - caveat: default values are not to be sent between Web API client and server, instead they are implied be the receiving side. Lapidary could potentially fill such values in response models, but it might be expensive, so it's not planned.
+        - nullable: if true, the property type is turned to `Union[None, $type]`
+        - readOnly & writeOnly: if either is true, the property type is turned to `Union[None, $type]` and has default value `None`; planned as part of docstr
+            - caveat: readOnly properties are only to be sent to API server, and writeOnly only to be received by the client. A property might be both required one way, and invalid the other way, which could not be directly represented in Python.
+        - discriminator: ignored
+        - example: might be used as part of docstr
+        - externalDocs: planned as part of docstr
+        - deprecated: planned
+        - xml: ignored, currently not planned
+    - responses
+        - description: planned as part of docstr
+        - headers: if present, used as fields in the response envelope class
+        - content: implemented; used as operation method return type, and a way to resolve model type for a response
+        - links: ignored; might be used to generate methods in the response envelope
+    - parameters: used in-line in operations
+    - examples: ignored
+    - requestBodies
+        - description: planned as part of docstr
+        - content: implemented
+        - required: planned
+    - headers: implemented
+    - securitySchemes: implemented with httpx_auth
+        - refreshUrl: not supported
+    - links: planned
+    - callbacks: not planned
+- paths
+    - summary, description: planned as parts of docstr
+    - servers: ignored
+    - parameters
+        - name: OpenAPI parameter names are not unique and might contain characters invalid for python names, therefore they're escaped and suffix-hungarian notation is used to distinguish between cookie, header, path and query parameters
+        - in: implemented, suffix-hungarian notation is used to separate parameters
+        - required: non-required parameters are optional with default value `None`
+        - deprecated: planned
+        - allowEmtyValue: planned
+        - content: key: planned, value: processed as schema
+        - style: partially implemented
+        - allowReserved: planned
+        - schema: implemented
+        - example & examples: planned
+        - x-lapidary-name: name of a parameter in the python
+- x-lapidary-responses-global: responses that might come from any operation
+- x-lapidary-headers-global: headers accepted by any operation

tests/e2e/expected/dummy/dummy.yaml

@@ -18,6 +18,8 @@ paths:
             x-count:
               schema:
                 type: integer
+        '300':
+          $ref: '#/components/responses/default'
       parameters:
       - name: param1
         in: query
@@ -34,7 +36,7 @@ paths:
           additionalProperties: false
           required:
           - prop1
-        required: true
+        required: false
   /inline_schema_properties/:
     get:
       operationId: inline_schema_properties
@@ -75,6 +77,8 @@ paths:
         - read
   /insecure:
     get:
+      requestBody:
+        $ref: '#/components/requestBodies/dummy'
       description: Operation with no security requirements
       operationId: insecure
       responses:
@@ -211,6 +215,20 @@ components:
           schema:
             $ref: '#/components/schemas/all'
       description: ''
+  requestBodies:
+    dummy:
+      required: false
+      description: ''
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              prop1:
+                type: string
+            additionalProperties: false
+            required:
+            - prop1
 
 security:
 - oauth-refresh:

tests/e2e/expected/dummy/gen/test_dummy/client.py

@@ -10,6 +10,7 @@
 import typing_extensions as typing
 from lapidary.runtime import *
 
+import test_dummy.components.requestBodies.dummy.content.applicationu_ljson.schema.schema
 import test_dummy.components.responses.default
 import test_dummy.components.schemas.schema1.schema
 import test_dummy.paths.u_lcustomu_jsecurity.get.responses.default
@@ -43,13 +44,16 @@ async def test_op(
         self: typing.Self,
         *,
         param1_q: typing.Annotated[test_dummy.components.schemas.schema1.schema.schema1, Query('param1', )],
-        param2_q: typing.Annotated[test_dummy.paths.u_ltestu_l.get.parameters.u_n.schema.schema.schema, Query('param2', )],
+        param2_q: typing.Annotated[typing.Union[None, test_dummy.paths.u_ltestu_l.get.parameters.u_n.schema.schema.schema], Query('param2', )] = None,
     ) -> typing.Annotated[
-        Awaitable[test_dummy.paths.u_ltestu_l.get.responses.default.Response],
+        Awaitable[typing.Union[test_dummy.components.responses.default.Response, test_dummy.paths.u_ltestu_l.get.responses.default.Response]],
         Responses({
             'default': {
                 'application/json': test_dummy.paths.u_ltestu_l.get.responses.default.Response,
             },
+            '300': {
+                'application/json': test_dummy.components.responses.default.Response,
+            },
         })
     ]:
         pass
@@ -83,6 +87,12 @@ async def customSecurity(
     @get('/insecure', security=[])
     async def insecure(
         self: typing.Self,
+        request_body: typing.Annotated[
+            test_dummy.components.requestBodies.dummy.content.applicationu_ljson.schema.schema.schema,
+            RequestBody({
+                'application/json': test_dummy.components.requestBodies.dummy.content.applicationu_ljson.schema.schema.schema,
+            }),
+        ],
     ) -> typing.Annotated[
         Awaitable[test_dummy.components.responses.default.Response],
         Responses({

tests/e2e/expected/dummy/gen/test_dummy/components/requestBodies/__init__.py

@@ -0,0 +1,2 @@
+# This file is automatically @generated by Lapidary and should not be changed by hand.
+

tests/e2e/expected/dummy/gen/test_dummy/components/requestBodies/dummy/__init__.py

@@ -0,0 +1,2 @@
+# This file is automatically @generated by Lapidary and should not be changed by hand.
+

tests/e2e/expected/dummy/gen/test_dummy/components/requestBodies/dummy/content/__init__.py

@@ -0,0 +1,2 @@
+# This file is automatically @generated by Lapidary and should not be changed by hand.
+

tests/e2e/expected/dummy/gen/test_dummy/components/requestBodies/dummy/content/applicationu_ljson/__init__.py

@@ -0,0 +1,2 @@
+# This file is automatically @generated by Lapidary and should not be changed by hand.
+

tests/e2e/expected/dummy/gen/test_dummy/components/requestBodies/dummy/content/applicationu_ljson/schema/__init__.py

@@ -0,0 +1,2 @@
+# This file is automatically @generated by Lapidary and should not be changed by hand.
+

tests/e2e/expected/dummy/gen/test_dummy/components/requestBodies/dummy/content/applicationu_ljson/schema/schema.py

@@ -0,0 +1,11 @@
+# This file is automatically @generated by Lapidary and should not be changed by hand.
+
+from __future__ import annotations
+
+import lapidary.runtime
+import pydantic
+import typing_extensions as typing
+
+
+class schema(lapidary.runtime.ModelBase):
+    prop1: str