Add some more method documentation

Author: usox

src/Contract/ApiMethodInterface.php

@@ -11,7 +11,11 @@
 interface ApiMethodInterface
 {
     /**
-     * @return array<mixed, mixed>
+     * This method contains the business logic of the api method
+     *
+     * @param stdClass $parameter The method parameter as described in the schema
+     *
+     * @return array<mixed, mixed> The api method response
      * 
      * @throws ApiMethodException
      */
@@ -20,5 +24,8 @@ public function handle(
         stdClass $parameter
     ): array;
 
+    /**
+     * Return the absolute path to the corresponding json schema
+     */
     public function getSchemaFile(): string;
 }

src/Contract/MethodProviderInterface.php

@@ -2,6 +2,13 @@
 
 namespace Usox\JsonSchemaApi\Contract;
 
+/**
+ * A method provider should perform a lookup an api method by its name.
+ * If api versions are used, the version number gets appended to the method name.
+ * e.g. someNamespace.someMethod, someNamespace.someMethod.1
+ *
+ * If the method name does not exist, lookup is expected to return null.
+ */
 interface MethodProviderInterface
 {
     public function lookup(

src/Endpoint.php

@@ -59,6 +59,9 @@ public function __construct(
         $this->logger = $logger;
     }
 
+    /**
+     * Try to execute the api handler and build the response
+     */
     public function serve(
         ServerRequestInterface $request,
         ResponseInterface $response
@@ -130,12 +133,17 @@ private function log(
             );
         }
     }
-    
+
+    /**
+     * Builds the endpoint.
+     * The StreamFactory can be omitted, the endpoint will search
+     * for any existing PSR17 implementations
+     */
     public static function factory(
         MethodProviderInterface $methodProvider,
         ?StreamFactoryInterface $streamFactory = null,
         ?LoggerInterface $logger = null
-    ): Endpoint {
+    ): EndpointInterface {
         $schemaValidator = new Validator();
         $schemaLoader = new SchemaLoader();