How it works

In construction...

Installing

Install Roxana in your M2 repository:

$ git clone https://github.com/rooting-company/roxana.git && ./roxana/mvnw.cmd install

Obs: Infortunately you need to install Roxana manualy, because it is not in maven central repository yet. We are solving this problem. ; )

Add Roxana as dependency of your project:

For Maven users: 
<dependencies>
  <dependency>
    <groupId>br.com.rooting</groupId>
    <artifactId>roxana</artifactId>
    <version>0.0.5-SNAPSHOT</version>
  </dependency>
</dependencies>
For Gradle users: 
compile group: 'br.com.rooting', roxana: 'commons-lang3', version: '0.0.5-SNAPSHOT'

Enable Roxana:

Just put @EnableRoxana in your Spring Rest API and that's it! 
@EnableRoxana
@SpringBootApplication
public class YourStringRestApplication {
  ...
}

Business Exceptions

Roxana allow you to create and launch Business Exceptions freely in your application. You don't need to worry about convert them to JSON responses in the top layer, or even create custom Spring's Controller Advice. This is possible because Roxana does that for you in a transparent way.

To create a business exception, you just need to map a Exception with Roxana's annotations like the snipped code below: 
package br.com.roxana.example;
...

// Your can define the Http Response e internationalization key if you don't want the default ones.
// If you don't want internationalization support put the plan massage 
// in the "message" field of the annotation.
@BusinessException
public class InsufficientFundsException extends Exception {

    // You can create different type of parameters,
    // by using @Parameter, @DateParameter or @CurrencyParameter.
    @CurrencyParameter
    private final BigDecimal funds;

    public InsufficientFundsException(BigDecimal funds) {
        this.funds = funds;
    }

}
If you define the following message in your I18n properties file: 
br.com.roxana.example.InsufficientFundsException = Saldo Insuficiente: [funds].
You will have the following JSON returned from your API: 
{
    "messages": [
    {
        "severity": "ERROR",
        "key": "{br.com.roxana.example.InsufficientFundsException}",
        "parameters": [
        {
            "funds": 3000.00
        }
        ],
        "language": "pt-BR",
        "translation": "Saldo Insuficiente: R$ 3000,00."
    }
    ]
}

OBS: The json format depends of configuration.

Here is a brief of the annotions used to map Business Exceptions:


  • @BusinessException: Indicate that the exception will be formmater as user's friendly massage by the Roxana default controller advice. It also allows you to define the HttpStatus Response that will be returned as response in your API.

    You can define a custom interpolation key (by default it is the cannonical name of the class) used in I18n support.
    If you don't want I18n support just use put a plan text in the interpolation key instanted of put between "{ }".

  • @Parameter: Map a field to be formated as string parameter of the message returned to the user.

  • @CurrencyParameter: Map a field to be formmated as a currency parameter (example: $ 10.00) of the message returned to the user.

  • @DateParameter: Map a field to be formmated as a date parameter (example: 2018/11/12) of the message returned to the user. It also provide flexibility in the way of format the dates.

There are others ways for Business Exceptions mapping that you may like. You can even create Multi Business Exception when you need to return a list of messages. Those features will be covered in the complete documentation.

Business Messages

In construction...

I18n Support

In construction...

Main Settings

In construction...