[GitHub] [ignite-3] valepakh commented on a diff in pull request #1028: IGNITE-16969 Add developer documentation to REST modules

[GitBox <gi...@apache.org>]

valepakh commented on code in PR #1028:
URL: https://github.com/apache/ignite-3/pull/1028#discussion_r952477609


##########
modules/rest-api/README.md:
##########
@@ -0,0 +1,30 @@
+# ignite-rest-api
+
+This module defines REST API's 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](todo) 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 [problem/json](todo) in all endpoints. That's why
+problem definition and common problem handling are defined in this module. Here is how it is working:

Review Comment:
   ```suggestion
   problem definition and common problem handling are defined in this module. Here is how it works:
   ```



##########
modules/rest-api/README.md:
##########
@@ -0,0 +1,30 @@
+# ignite-rest-api
+
+This module defines REST API's that might be provided by Ignite 3. Also, common

Review Comment:
   ```suggestion
   This module defines REST APIs that might be provided by Ignite 3. Also, common
   ```



##########
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:
+
+- at compile time it aggregates all REST API definitions by `@OpenAPIInclude` annotation
+- at runtime, it creates a micronaut context, injects all needed beans into the context
+- starts the micronaut server at the configured port range
+
+During the build time, the [Open API spec]() 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 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)

Review Comment:
   ```suggestion
   - API definition [ClusterManagementApi](../rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterManagementApi.java)
   ```



##########
modules/rest-api/README.md:
##########
@@ -0,0 +1,30 @@
+# ignite-rest-api
+
+This module defines REST API's 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](todo) from these interfaces.

Review Comment:
   Why there's no link to the spec?



##########
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:
+
+- at compile time it aggregates all REST API definitions by `@OpenAPIInclude` annotation
+- at runtime, it creates a micronaut context, injects all needed beans into the context
+- starts the micronaut server at the configured port range
+
+During the build time, the [Open API spec]() is generated from all API definitions that are included in

Review Comment:
   Empty link



##########
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:
+
+- at compile time it aggregates all REST API definitions by `@OpenAPIInclude` annotation
+- at runtime, it creates a micronaut context, injects all needed beans into the context
+- starts the micronaut server at the configured port range
+
+During the build time, the [Open API spec]() 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 IgniteImpl constructor and put the factory to the RestComponent's constructor

Review Comment:
   ```suggestion
   - create the instance of the RestFactory in the IgniteImpl constructor and put the factory to the RestComponent's constructor
   ```



##########
modules/rest-api/README.md:
##########
@@ -0,0 +1,30 @@
+# ignite-rest-api
+
+This module defines REST API's 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](todo) 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 [problem/json](todo) in all endpoints. That's why

Review Comment:
   todo again



##########
modules/rest-api/README.md:
##########
@@ -0,0 +1,30 @@
+# ignite-rest-api
+
+This module defines REST API's 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](todo) 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 [problem/json](todo) in all endpoints. That's why
+problem definition and common problem handling are defined in this module. Here is how it is working:
+
+- `IgniteException` 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` and returns a valid `problem/json`

Review Comment:
   I wonder why there's a link to the IgniteExceptionHandler file but not to the IgniteException?



##########
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:
+
+- at compile time it aggregates all REST API definitions by `@OpenAPIInclude` annotation
+- at runtime, it creates a micronaut context, injects all needed beans into the context
+- starts the micronaut server at the configured port range

Review Comment:
   ```suggestion
   - 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
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@ignite.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org