[ignite-3] branch main updated: IGNITE-16969 Added developer documentation to REST modules. Fixes #1028

[sk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sk0x50 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ignite-3.git


The following commit(s) were added to refs/heads/main by this push:
     new 53896eb702 IGNITE-16969 Added developer documentation to REST modules. Fixes #1028
53896eb702 is described below

commit 53896eb7024dafbfd008af21b4488c3bb7063b25
Author: Aleksandr Pakhomov <ap...@gmail.com>
AuthorDate: Tue Aug 30 09:58:32 2022 +0300

    IGNITE-16969 Added developer documentation to REST modules. Fixes #1028
    
    Signed-off-by: Slava Koptilin <sl...@gmail.com>
---
 modules/README.md          |  3 ++-
 modules/rest-api/README.md | 31 +++++++++++++++++++++++++++
 modules/rest/README.md     | 52 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 85 insertions(+), 1 deletion(-)

diff --git a/modules/README.md b/modules/README.md
index a58e6aa5f7..7201ca4893 100644
--- a/modules/README.md
+++ b/modules/README.md
@@ -19,7 +19,8 @@ Module Name | Description
 [core: causality tokens](core/src/main/java/org/apache/ignite/internal/causality/README.md)|Causality tokens
 [core: local state recovery](core/src/main/java/org/apache/ignite/internal/manager/RECOVERY.md)|Local state recovery
 [network](network/README.md)|Networking module: group membership and message passi
-[rest](rest/README.md)|REST management endpoint bindings and command handlers
+[rest](rest/README.md)|REST server and Open API spec generation
+[rest-api](rest-api/README.md)|REST API interfaces
 [runner](runner/README.md)|Ignite server node runner. The module that wires up the Ignite components and handles node lifecycle.
 [schema](schema/README.md)|Ignite schema API implementation and schema management classes.
 [table](table/README.md)|Ignite table API implementation.
diff --git a/modules/rest-api/README.md b/modules/rest-api/README.md
new file mode 100644
index 0000000000..9145937474
--- /dev/null
+++ b/modules/rest-api/README.md
@@ -0,0 +1,31 @@
+# ignite-rest-api
+
+This module defines REST APIs that might be provided by Ignite 3. Also, common
+DTOs and error handlers are defined.
+
+## API definition
+
+The API definition is a java interface annotated with micronaut `@Controller`  
+annotations and several `swagger-annotations`. All those annotations are 
+needed to generate a valid [Open API spec](https://spec.openapis.org/oas/v3.1.0) from these interfaces.
+
+[ClusterManagementApi](src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterManagementApi.java) is an example of API definition.
+
+## Error handling
+
+Ignite 3 implements the [application/problem+json](https://www.rfc-editor.org/rfc/rfc7807.html) in all endpoints. That's why
+problem definition and common problem handling are defined in this module. Here is how it works:
+
+- [`IgniteException`](../api/src/main/java/org/apache/ignite/lang/IgniteException.java) is thrown in any Ignite component
+- REST Controller might not handle this exception 
+- [`IgniteExceptionHandler`](src/main/java/org/apache/ignite/internal/rest/exception/handler/IgniteExceptionHandler.java) 
+is invoked by micronaut infrastructure
+- [`IgniteExceptionHandler`](src/main/java/org/apache/ignite/internal/rest/exception/handler/IgniteExceptionHandler.java)  handles 
+[`IgniteException`](../api/src/main/java/org/apache/ignite/lang/IgniteException.java) and returns a valid `application/problem+json`
+
+> Make sure that [`IgniteExceptionHandler`](src/main/java/org/apache/ignite/internal/rest/exception/handler/IgniteExceptionHandler.java)
+> has been loaded into micronaut context otherwise this class won't be invoked.
+
+If you want to implement your exception handler the best place to do it 
+is the module where you define the REST controller. Don't put your handlers in
+`ignite-rest-api` unless it is needed for all REST endpoints.
diff --git a/modules/rest/README.md b/modules/rest/README.md
new file mode 100644
index 0000000000..36d494c32b
--- /dev/null
+++ b/modules/rest/README.md
@@ -0,0 +1,52 @@
+# ignite-rest
+
+This module defines [RestComponent](src/main/java/org/apache/ignite/internal/rest/RestComponent.java) that is responsible for:
+
+- aggregating all REST API definitions by `@OpenAPIInclude` annotation at compile time
+- creating a micronaut context at runtime and injecting all needed beans into the context
+- starting the micronaut server at the configured port range
+
+During the build time, the [Open API spec](https://spec.openapis.org/oas/v3.1.0) is generated from all API definitions that are included in
+`@OpenAPIInclude` annotation. The spec is located in `ignite-rest/openapi`.
+
+## How to create a new REST Endpoint
+
+- define API in `ignite-rest-api` module
+- link the API interface in `RestComponent`'s `@OpenAPIInclude` section
+- implement an API interface in the module that is responsible for the API scope
+- define micronaut factory that is responsible for the creation of beans that are needed for your Controller
+- for extending the exception handling mechanism, implement micronaut's `ExceptionHandler` and include it in the micronaut factory
+- create the instance of the RestFactory in the IgniteImpl constructor and put the factory to the RestComponent's constructor
+
+> The class that implements the API should be a valid micronaut controller.
+> Module with the API implementation should configure `micronaut-inject-java` annotation processor.
+
+> Micronaut factories have to implement `RestFactory` from `ignite-rest-api` 
+
+## Example of REST Endpoint
+
+- API definition [ClusterManagementApi](../rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterManagementApi.java)
+- API implementation [ClusterManagementController](../cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/rest/ClusterManagementController.java)
+- `RestFactory` implementation [ClusterManagementRestFactory](../cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/rest/ClusterManagementRestFactory.java)
+- `ExceptionHandler` implementation [ClusterNotInitializedExceptionHandler](../cluster-management/src/main/java/org/apache/ignite/internal/cluster/management/rest/exception/handler/ClusterNotInitializedExceptionHandler.java)
+
+## Architecture of REST server
+
+`ignite-rest-api` module defines only API without any implementation. 
+The main value of this module is to provide all needed information to generate an Open API spec.
+
+REST server is started by [RestComponent](src/main/java/org/apache/ignite/internal/rest/RestComponent.java) in `ignite-rest` module.
+This module also configures `micronaut-openapi` generator and generates an Open API spec during the build time.
+But the only dependency of the `ignite-rest` is `ignite-rest-api`. **There is no dependency on any module that provides API implementation.**
+
+REST Controllers together with RestFactories are set to RestComponent at runtime by IgniteImpl through the constructor.
+
+
+## How to test REST Endpoints
+
+Unit tests can be defined at the same module where the Controller is implemented, see [ClusterConfigurationControllerTest](../configuration/src/test/java/org/apache/ignite/internal/rest/configuration/ClusterConfigurationControllerTest.java).
+To make them work test dependencies should include `micronaut-test-junit5`, `micronaut-http-client`, `micronaut-http-server-netty`. 
+Also, `micronaut-inject-java` annotation processor should be configured.
+
+Integration tests could be defined in runner module, see `ItInitializedClusterRestTest` and `ItNotInitializedClusterRestTest`.
+