add docs

docs/features/discriminator.md

@@ -1,2 +1,35 @@
 # Discriminator
 Generate [pydantic classes with discriminators](https://docs.pydantic.dev/latest/api/standard_library_types/#discriminated-unions-aka-tagged-unions) based on [OpenAPI discriminators](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/). The original OpenAPI specification must have the propertyName and mapping fields.
+
+
+## Example
+For OpenAPI schema
+```yaml
+DiscriminatedOneOfResp:
+      title: All Of Resp
+      type: object
+      required: ['required_discriminated_animal']
+      properties:
+        discriminated_animal:
+          discriminator:
+            mapping: {cat: '#/components/schemas/CatWithKind', dog: '#/components/schemas/DogWithKind'}
+            propertyName: kind
+          oneOf:
+            - {$ref: '#/components/schemas/CatWithKind'}
+            - {$ref: '#/components/schemas/DogWithKind'}
+          title: Animal
+        required_discriminated_animal:
+          discriminator:
+            mapping: {cat: '#/components/schemas/CatWithKind', dog: '#/components/schemas/DogWithKind'}
+            propertyName: kind
+          oneOf:
+            - {$ref: '#/components/schemas/CatWithKind'}
+            - {$ref: '#/components/schemas/DogWithKind'}
+          title: Animal
+```
+the following class will be generated
+```python
+class DiscriminatedOneOfResp(BaseModel):
+    required_discriminated_animal: CatWithKind | DogWithKind = Field(..., discriminator="kind")
+    discriminated_animal: CatWithKind | DogWithKind | None = Field(None, discriminator="kind")
+```

docs/features/property_safety_name.md

@@ -1,6 +1,38 @@
 # Property safety name
-You can explicitly specify the name with which the property will be generated for the data schema. To do this, specify the desired name in the property description in the format `__safety_key__(your_name)`.
+Promerty names are automatically converted to secure python names. However, you can explicitly specify the name with which the property will be generated for the data schema. To do this, specify the desired name in the property description in the format `__safety_key__(your_name)`.
 
+## Auto converted names
+For OpenAPI schema with not safety property names `for`, `class`, `33with.dot-and-hyphens&*`
+```yaml
+SafetyKeyForTesting:
+      title: model for testing safety key
+      type: object
+      properties:
+        for:
+          title: For
+          type: string
+          description: reserved word, expecting "for_"
+        class:
+          title: Class
+          type: string
+          description: reserved word, expecting "class_"
+        33with.dot-and-hyphens&*:
+          title: With dot, hyphens and garbage
+          type: integer
+          description: invalid identifier, expecting "with_dot_and_hyphens"
+```
+
+the following class with  safety property names `for_`, `class_`, `with_dot_and_hyphens` will be generated
+```python
+class SafetyKeyForTesting(BaseModel):
+    for_: str | None = Field(None, alias="for", description='reserved word, expecting "for_"')
+    class_: str | None = Field(None, alias="class", description='reserved word, expecting "class_"')
+    with_dot_and_hyphens: int | None = Field(
+        None, alias="33with.dot-and-hyphens&*", description='invalid identifier, expecting "with_dot_and_hyphens"'
+    )
+```
+
+## Custom names
 For example, for the original schema with not safety property `event-data`
 ```yaml
 PostObjectData: