Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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
- Host: GitHub
- URL: https://github.com/dream11/vertx-rest
- Owner: dream11
- License: mit
- Created: 2021-12-23T07:02:35.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-04-03T02:34:45.000Z (9 months ago)
- Last Synced: 2024-09-27T07:41:27.498Z (3 months ago)
- Topics: jax-rs, vertx
- Language: Java
- Homepage: https://dream11.github.io/vertx-rest/
- Size: 56.6 KB
- Stars: 42
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- vertx-awesome - vertx-rest - Abstraction over resteasy-vertx to simplify writing a Vert.x REST application based on JAX-RS annotations. (Web Frameworks)
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)