Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dream11/vertx-rest

Writing vertx rest application based on JAX-RS applications
https://github.com/dream11/vertx-rest

jax-rs vertx

Last synced: 2 months ago
JSON representation

Writing vertx rest application based on JAX-RS applications

Awesome Lists containing this project

README

        

# vertx-rest
[![Continuous Integration](https://github.com/dream11/vertx-rest/actions/workflows/ci.yml/badge.svg)](https://github.com/dream11/vertx-rest/actions/workflows/ci.yml)
[![Code Coverage](https://codecov.io/gh/dream11/vertx-rest/branch/master/graph/badge.svg)](https://codecov.io/gh/dream11/vertx-rest)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://raw.githubusercontent.com/dream11/vertx-rest/master/LICENSE)

- [Overview](#overview)
- [Setup](#setup)
- [How to use](#usage)
- [Rest Verticle](#create-rest-verticle)
- [JAX-RS Routes](#create-a-rest-resource)
- [Validations](#validations)
- [Exception Handling](#exception-handling)
- [Dependency Injection](#dependency-injection)
- [Custom Providers](#custom-providers)
- [Timeouts](#timeouts)
- [Examples](#examples)
- [Swagger](#swagger-specification)
- [References](#references)

## Overview
- Abstraction over [resteasy-vertx](https://github.com/resteasy/resteasy/tree/main/server-adapters/resteasy-vertx) to simplify writing a
vertx REST application based on JAX-RS annotations
- Provides a [backpressure](https://github.com/ReactiveX/RxJava/wiki/Backpressure) enabled HTTP server to drop requests on high load
- Exception mappers to standardise error response
- Timeout annotation for closing long-running requests
- Uses `rxjava3`

## Setup

Add the following dependency to the `dependencies` section of your build descriptor:

- Maven (in your `pom.xml`):
```xml

com.dream11
vertx-rest
x.y.z

```

- Gradle (in your `build.gradle` file):
```
dependencies {
compile 'com.dream11:vertx-rest:x.y.z'
}
```

Note: Replace `x.y.z` above with one of the [released versions](https://github.com/dream11/vertx-rest/releases)

## Usage

### Create Rest Verticle
Create the application REST Verticle by extending `com.dream11.rest.AbstractRestVerticle` class.
The `AbstractRestVerticle` here does the following:
* Finds all the resources(i.e, classes annotated with `@Path`) in the package and adds an instance of each of the resource classes to
the resteasy-deployment registry
* Adds all the `Filters` and `ExceptionMappers` and any other custom `Providers` to the resteasy-deployment
* Starts a backpressure enabled HTTP server and dispatches each request to the handler registered with the resteasy-deployment

```java
public class RestVerticle extends AbstractRestVerticle {

public RestVerticle() {
// starts http server with default options
// All classes with @Path annotation in the specified package are registered with the router
super("com.dream11.package");
}

@Override
protected ClassInjector getInjector() {
// Add your implmentation of injector
return null;
}
}
```

Use the following constructor to pass custom HTTP Server Options

```java
public RestVerticle() {
super("com.dream11.package", new HttpServerOptions().setPort(8080)); // starts http server with provided options
}
```

### Create a Rest Resource

```java
@Path("/test")
public class TestRoute {

@GET
@Consumes(MediaType.WILDCARD)
@Produces(MediaType.APPLICATION_JSON)
@ApiResponse(content = @Content(schema = @Schema(implementation = String.class)))
public CompletionStage test() {
return Single.just("Hello World")
.toCompletionStage();
}
}
```

## Validations
* Use all the jakarta constraints given [here](https://jakarta.ee/specifications/bean-validation/3.0/apidocs/jakarta/validation/constraints/package-summary.html)
* You can use `@TypeValidationError(code=, message=)` on DTO parameters to send custom error code and message
when parsing of parameter fails
* `@TypeValidationError` can also be used for `Integer`, `Long`, `Float` or `Double` types in `@HeaderParam`, `@QueryParam` etc. If you
want to use `@TypeValidationError` on a parameter of type other than these types you can create a custom converter similar to `IntegerParamConverter` and a provider extending `ParamConverterProvider`. [Reference](https://blog.sebastian-daschner.com/entries/jaxrs-convert-params)

## Exception Handling
- Provides exceptions and exception mappers to standardize error response
- Implement `RestError` as an enum to specify error codes, messages and http status codes to be returned in response for your exceptions
- Throw `RestException` with the restError to return error response in the following format
```json
{
"error": {
"code": "UNKNOWN_EXCEPTION",
"message": "Something went wrong",
"cause": "Cannot connect to mysql database"
}
}
```
- Refer to the package [`com.dream11.rest.exception.mapper`](src/main/java/com/dream11/rest/exception/mapper) for mappers provided by
default
- Implement your own exception mappers if you need some other error response

## Timeouts
- Configure request timeout by annotating your JAX-RS resource classes with `@Timeout(value = , httpStatusCode =
)`
- Default timeout for each JAX-RS route is `20` seconds
- Since there is no official HTTP Status code for origin server timeout, it has been kept configurable. By default `500` status code
is returned in case of timeouts.

## Dependency Injection
- Implement abstract method `getInjector` of `AbstractRestVerticle` to return an implementation of the `ClassInjector` interface
- This will be used for injecting instances of the REST resource classes
- Refer to [`com.dream11.rest.injector.GuiceInjector`](src/test/java/com/dream11/rest/injector/GuiceInjector.java) for an example

## Custom Providers
- Annotate your provider classes with `@Provider` to automatically register them with resteasy deployment

- Alternatively, if your provider class necessitates a constructor with parameters, you can override the following method in
[AbstractRestVerticle](src/main/java/com/dream11/rest/AbstractRestVerticle.java) to register the provider object
```java
public class RestVerticle extends AbstractRestVerticle {

@Override
protected List getProviderObjects() {
List providerObjects = super.getProviderObjects();
// add your provider object with custom constructor to the list
return providerObjects;
}
}
```

### Custom Json Provider
You can create custom json providers by
- Implement the `JsonProvider` interface, defined in [JsonProvider](src/main/java/com/dream11/rest/provider/JsonProvider.java) and then,
- Override the following method in [AbstractRestVerticle](src/main/java/com/dream11/rest/AbstractRestVerticle.java)
```java
public class RestVerticle extends AbstractRestVerticle {

@Override
protected JsonProvider getJsonProvider() {
// return your custom json provider
}
}
```

## Examples
Please refer [tests](/src/test/java/com/dream11/rest) for an example application

## Swagger Specification
Follow [this](/docs/swagger/swagger-generation.md) doc to generate swagger specification.

## References

* [Swagger Maven Plugin](https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-maven-plugin)
* [Resteasy Vertx](https://docs.jboss.org/resteasy/docs/3.1.0.Final/userguide/html/RESTEasy_Embedded_Container.html)
* [Hibernate Validations](https://hibernate.org/validator/documentation/getting-started/)
* [Jakarta Validation Constraints](https://jakarta.ee/specifications/bean-validation/3.0/apidocs/jakarta/validation/constraints/package-summary.html)
* [JAX-RS](https://docs.oracle.com/javaee/6/tutorial/doc/gilik.html)
* [Swagger Annotations](https://github.com/swagger-api/swagger-core/wiki/Annotations)