- Updated docs

- Fixed some mypy complaints about pydantic models and typing

Author: MarcoMuellner

.flake8

@@ -1,6 +1,6 @@
 [flake8]
 select = B,B9,BLK,C,E,F,I,W,S
-max-complexity = 15
+max-complexity = 20
 application-import-names = openapi_python_generator
 import-order-style = google
 ignore = E203,E501,W503

docs/tutorial/advanced.md

@@ -0,0 +1,3 @@
+# Advanced usage
+
+__coming soon__

docs/tutorial/authentication.md

@@ -0,0 +1,3 @@
+# Authentication
+
+__coming soon__

docs/tutorial/index.md

@@ -2,7 +2,7 @@
 
 ## Pre requisits
 
-As already denoted in [the quick start section](quick_start.md), the first thing
+As already denoted in [the quick start section](../quick_start.md), the first thing
 you need to do is to actually install the generator. You can do so via pip
 or any other package manager.
 
@@ -593,7 +593,7 @@ suite of the generator. It has the following structure:
 !!! tip "OpenAPI specification"
 
     Take a look at our short introduction to the
-    [OpenAPI specification](openapi-definition.md) if you need to look up
+    [OpenAPI specification](../openapi-definition.md) if you need to look up
     what the specific nodes mean, or if you just need a refresher or some
     links for further information.
 
@@ -605,7 +605,7 @@ Lets run the generator on this file:
 </div>
 
 This will result in the folder structure as denoted in the
-[quick start](quick_start.md) section. Lets take a deep dive on what
+[quick start](../quick_start.md) section. Lets take a deep dive on what
 the generator created for us, starting with the models.
 
 ## The models module
@@ -763,3 +763,108 @@ the additional two - four modules.
 The next thing is async support: You may want (depending on your usecase)
 bot async and sync services. The generator will create both (for __httpx__),
 only sync (for __requests__) or only async (for __aiohttp__) services.
+
+=== "async_general_service.py"
+    ``` py
+    ...
+    async def async_root__get() -> RootResponse:
+        base_path = APIConfig.base_path
+        path = f"/"
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Authorization": f"Bearer { APIConfig.get_access_token() }",
+        }
+        query_params = {}
+
+        with httpx.AsyncClient(base_url=base_path) as client:
+            response = await client.request(
+                method="get",
+                url=path,
+                headers=headers,
+                params=query_params,
+            )
+
+        if response.status_code != 200:
+            raise Exception(f" failed with status code: {response.status_code}")
+        return RootResponse(**response.json())
+    ...
+    ```
+
+=== "general_service.py"
+    ``` py
+    ...
+    def root__get() -> RootResponse:
+        base_path = APIConfig.base_path
+        path = f"/"
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Authorization": f"Bearer { APIConfig.get_access_token() }",
+        }
+        query_params = {}
+
+        with httpx.Client(base_url=base_path) as client:
+            response = client.request(
+                method="get",
+                url=path,
+                headers=headers,
+                params=query_params,
+            )
+
+        if response.status_code != 200:
+            raise Exception(f" failed with status code: {response.status_code}")
+        return RootResponse(**response.json())
+    ...
+    ```
+
+While we are at the topic of looking at the individual functions, lets walk through the one above:
+
+```py
+...
+def root__get() -> RootResponse:
+...
+```
+
+All functions are fully annotated with the proper types, which provides the inspection of your IDE better insight
+on what to provide to a given function and what to expect.
+
+```py
+...
+path = f"/"
+...
+```
+
+Paths are automatically created from the specification. No need to worry about that.
+
+```py
+...
+headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Authorization": f"Bearer { APIConfig.get_access_token() }",
+        }
+query_params = {}
+...
+```
+
+Authorization token is always passed to the Rest API, you will not need to worry about differentiating between the
+calls. Query params are also automatically created, with the input parameters and depending on your spec (for
+this root call no params are necessary)
+
+```py
+...
+if response.status_code != 200:
+    raise Exception(f" failed with status code: {response.status_code}")
+return RootResponse(**response.json())
+...
+```
+
+The generator will automatically raise an exception if a non-good status code was returned by the API, for
+whatever reason. The "good" status code is also determined by the spec - and can be defined through your API.
+For a post call for example, the spec will define a 201 status code as a good status code.
+
+Lastly the code will automatically type check and convert the response to the appropriate type (in this case
+`RootResponse`). This is really neat, because without doing much in the code, it automatically validates that
+your API truly responds the way we expect it to respond, and gives you proper typing latter on in your code -
+all thanks to the magic of [pydantic](https://pydantic-docs.helpmanual.io/).

mkdocs.yml

@@ -23,13 +23,14 @@ theme:
     - search.suggest
     - search.highlight
     - content.tabs.link
+    - content.code.annotate
   icon:
     repo: fontawesome/brands/github-alt
 markdown_extensions:
-  - attr_list
-  - md_in_html
   - pymdownx.superfences
   - admonition
+  - attr_list
+  - md_in_html
   - pymdownx.tabbed:
       alternate_style: true
 nav:
@@ -38,7 +39,8 @@ nav:
   - quick_start.md
   - Tutorial - User Guide:
       - tutorial/index.md
-      - tutorial/module_usage.md
+      - tutorial/authentication.md
+      - tutorial/advanced.md
   - References :
       - references/index.md
   - Acknowledgements:

mypy.ini

@@ -1,4 +1,5 @@
 [mypy]
+plugins = pydantic.mypy
 
 [mypy-nox.*,pytest]
 ignore_missing_imports = True

src/openapi_python_generator/generate_data.py

@@ -7,6 +7,7 @@
 import httpx
 import isort
 import orjson
+from black import NothingChanged
 from httpx import ConnectError
 from httpx import ConnectTimeout
 from openapi_schema_pydantic import OpenAPI
@@ -28,9 +29,12 @@ def write_code(path: Path, content) -> None:
     :param content: The content to write.
     """
     with open(path, "w") as f:
-        formatted_contend = black.format_file_contents(
-            content, fast=False, mode=black.FileMode(line_length=120)
-        )
+        try:
+            formatted_contend = black.format_file_contents(
+                content, fast=False, mode=black.FileMode(line_length=120)
+            )
+        except NothingChanged:
+            formatted_contend = content
         formatted_contend = isort.code(formatted_contend, line_length=120)
         f.write(formatted_contend)
 

src/openapi_python_generator/language_converters/python/generator.py

@@ -22,8 +22,16 @@ def generator(
     Generate Python code from an OpenAPI 3.0 specification.
     """
 
-    models = generate_models(data.components)
-    services = generate_services(data.paths, library_config)
+    if data.components is not None:
+        models = generate_models(data.components)
+    else:
+        models = []
+
+    if data.paths is not None:
+        services = generate_services(data.paths, library_config)
+    else:
+        services = []
+
     api_config = generate_api_config(data, env_token_name)
 
     return ConversionResult(

src/openapi_python_generator/language_converters/python/model_generator.py

@@ -1,3 +1,4 @@
+import itertools
 from typing import List
 from typing import Optional
 
@@ -33,12 +34,26 @@ def type_converter(schema: Schema, required: bool = False) -> TypeConversion:
         post_type = "]"
 
     original_type = schema.type
-    import_types = None
+    import_types: Optional[List[str]] = None
 
     if schema.allOf is not None:
-        conversions = [type_converter(i, True) for i in schema.allOf]
+        conversions = []
+        for sub_schema in schema.allOf:
+            if isinstance(sub_schema, Schema):
+                conversions.append(type_converter(sub_schema, True))
+            else:
+                import_types = [sub_schema.ref.split("/")[-1]]
+                conversions.append(
+                    TypeConversion(
+                        original_type=sub_schema.ref,
+                        converted_type=import_types[0],
+                        import_types=import_types,
+                    )
+                )
 
-        original_type = "tuple<" + ",".join([i.type for i in schema.allOf]) + ">"
+        original_type = (
+            "tuple<" + ",".join([i.original_type for i in conversions]) + ">"
+        )
         converted_type = (
             pre_type
             + "Tuple["
@@ -47,23 +62,40 @@ def type_converter(schema: Schema, required: bool = False) -> TypeConversion:
             + post_type
         )
         import_types = [
-            i.import_types for i in conversions if i.import_types is not None
+            i.import_types[0] for i in conversions if i.import_types is not None
         ]
 
     elif schema.oneOf is not None or schema.anyOf is not None:
         used = schema.oneOf if schema.oneOf is not None else schema.anyOf
-        conversions = [type_converter(i, True) for i in used]
-        original_type = "union<" + ",".join([i.type for i in used]) + ">"
+        used = used if used is not None else []
+        conversions = []
+        for sub_schema in used:
+            if isinstance(sub_schema, Schema):
+                conversions.append(type_converter(sub_schema, True))
+            else:
+                import_types = [sub_schema.ref.split("/")[-1]]
+                conversions.append(
+                    TypeConversion(
+                        original_type=sub_schema.ref,
+                        converted_type=import_types[0],
+                        import_types=import_types,
+                    )
+                )
+        original_type = (
+            "union<" + ",".join([i.original_type for i in conversions]) + ">"
+        )
         converted_type = (
             pre_type
             + "Union["
             + ",".join([i.converted_type for i in conversions])
             + "]"
             + post_type
         )
-        import_types = [
-            i.import_types for i in conversions if i.import_types is not None
-        ]
+        import_types = list(
+            itertools.chain(
+                *[i.import_types for i in conversions if i.import_types is not None]
+            )
+        )
     elif schema.type == "string":
         converted_type = pre_type + "str" + post_type
     elif schema.type == "integer":
@@ -165,7 +197,10 @@ def generate_models(components: Components) -> List[Model]:
     :param components: The components from an OpenAPI 3.0 specification.
     :return: A list of models.
     """
-    models = []
+    models: List[Model] = []
+
+    if components.schemas is None:
+        return models
 
     for name, schema_or_reference in components.schemas.items():
         if schema_or_reference.enum is not None:
@@ -175,7 +210,6 @@ def generate_models(components: Components) -> List[Model]:
                     name=name, **schema_or_reference.dict()
                 ),
                 openapi_object=schema_or_reference,
-                references=[],
                 properties=[],
             )
             try:
@@ -187,7 +221,12 @@ def generate_models(components: Components) -> List[Model]:
             continue  # pragma: no cover
 
         properties = []
-        for prop_name, property in schema_or_reference.properties.items():
+        property_iterator = (
+            schema_or_reference.properties.items()
+            if schema_or_reference.properties is not None
+            else {}
+        )
+        for prop_name, property in property_iterator:
             if isinstance(property, Reference):
                 conv_property = _generate_property_from_reference(
                     prop_name, property, schema_or_reference