Reference docs

Author: p1c2u

docs/reference/index.md

@@ -0,0 +1,3 @@
+# Reference
+
+Documentation with information of functions, classes or methods and all other parts of the OpenAPI-core public API.

docs/reference/openapi.md

@@ -0,0 +1,9 @@
+# `OpenAPI` class
+
+::: openapi_core.OpenAPI
+    options:
+        members:
+            - from_dict
+            - from_path
+            - from_file_path
+            - from_file

mkdocs.yml

@@ -46,6 +46,13 @@ theme:
     - toc.follow
 repo_name: python-openapi/openapi-core
 repo_url: https://github.com/python-openapi/openapi-core
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            extensions:
+              - griffe_typingdoc
 nav:
   - OpenAPI-core: index.md
   - unmarshalling.md
@@ -75,6 +82,9 @@ nav:
     - customizations/extra_format_unmarshallers.md
   - security.md
   - extensions.md
+  - Reference:
+    - reference/index.md
+    - reference/openapi.md
   - contributing.md
 markdown_extensions:
   - admonition

openapi_core/app.py

@@ -14,6 +14,8 @@
 from openapi_spec_validator.versions.datatypes import SpecVersion
 from openapi_spec_validator.versions.exceptions import OpenAPIVersionNotFound
 from openapi_spec_validator.versions.shortcuts import get_spec_version
+from typing_extensions import Annotated
+from typing_extensions import Doc
 
 from openapi_core.configurations import Config
 from openapi_core.exceptions import SpecError
@@ -72,11 +74,28 @@
 
 
 class OpenAPI:
-    """OpenAPI class."""
+    """`OpenAPI` application class, the main entrypoint class for OpenAPI-core.
+
+    Read more information, in the 
+    [OpenAPI-core docs for First Steps](https://openapi-core.readthedocs.io/#first-steps).
+
+    Import :class:`OpenAPI` class from the main `openapi_core` module::
+
+        from openapi_core import OpenAPI
+
+        app = OpenAPI(spec)
+    """
 
     def __init__(
         self,
-        spec: SchemaPath,
+        spec: Annotated[
+            SchemaPath,
+            Doc(
+                """
+                OpenAPI specification schema path object.
+                """
+            ),
+        ],
         config: Optional[Config] = None,
     ):
         if not isinstance(spec, SchemaPath):
@@ -91,20 +110,23 @@ def __init__(
     def from_dict(
         cls, data: Schema, config: Optional[Config] = None, base_uri: str = ""
     ) -> "OpenAPI":
+        """Creates :class:`OpenAPI` class instance from a dictionary."""
         sp = SchemaPath.from_dict(data, base_uri=base_uri)
         return cls(sp, config=config)
 
     @classmethod
     def from_path(
         cls, path: Path, config: Optional[Config] = None
     ) -> "OpenAPI":
+        """Creates :class:`OpenAPI` class instance from a path object."""
         sp = SchemaPath.from_path(path)
         return cls(sp, config=config)
 
     @classmethod
     def from_file_path(
         cls, file_path: str, config: Optional[Config] = None
     ) -> "OpenAPI":
+        """Creates :class:`OpenAPI` class instance from a file path string."""
         sp = SchemaPath.from_file_path(file_path)
         return cls(sp, config=config)
 
@@ -115,6 +137,7 @@ def from_file(
         config: Optional[Config] = None,
         base_uri: str = "",
     ) -> "OpenAPI":
+        """Creates :class:`OpenAPI` class instance from a file object."""
         sp = SchemaPath.from_file(fileobj, base_uri=base_uri)
         return cls(sp, config=config)
 

poetry.lock

@@ -117,6 +117,7 @@ fastapi = ">=0.111,<0.115"
 mkdocs = "^1.6.1"
 mkdocstrings = {extras = ["python"], version = "^0.26.1"}
 mkdocs-material = "^9.5.34"
+griffe-typingdoc = "^0.2.7"
 
 [tool.pytest.ini_options]
 addopts = """