-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
π Update OpenAPI compatibility doc.
- Loading branch information
1 parent
6ec9fda
commit d44003c
Showing
1 changed file
with
74 additions
and
73 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,75 +1,76 @@ | ||
# 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 | ||
- β `openapi`: validated (3.0.* accepted) | ||
- `info` | ||
- β `license`: N/A; 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 | ||
- `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 | ||
- β assertion keywords: as supported by pydantic | ||
- β οΈ `allOf`: needs improvement | ||
- β `anyOf`: implemented as union | ||
- β οΈ `oneOf`: treated as `anyOf` and 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 would be an optional feature. | ||
- β `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, except with two or three classes for every schema. | ||
- β `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`: currently 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 | ||
- ποΈ `allowEmptyValue`: planned | ||
- ποΈ `content`: key: planned, value: processed as schema | ||
- β οΈ `style`: partially implemented | ||
- ποΈ `allowReserved`: planned | ||
- β `schema`: implemented | ||
- π `example` & examples: considered | ||
- π§ `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 |