Extension

VisualBoost makes it easy to customize your application and add your own business logic by allowing you to create Extensions. These Extensions are custom REST routes that can run their own unique functionality and are linked to specific models. For each model, you can add as many REST routes as you need. You can also synchronize these Extensions with VisualBoost, ensuring they fully integrate into your software architecture. Once synchronized, your Extensions will automatically be included in the documentation.

We recommend using the VisualBoost plugin to create extensions easily and comfortably.

Each Extension is part of a JavaScript file named after the corresponding model. To ensure it is recognized during synchronization, this file must be placed in the Extensions folder, which can be set in VisualBoost’s settings.

./extension/Person.js

const router = require("express").Router();
const mongoose = require("mongoose");
const Person = require("../../db/generated/Person");

/**
 * Get a persons' name
 *
 * @name: getName
 *
 * @return: {
 *      name: String
 * }
 *
 * @errors: {
 *     400: "Bad Request",
 *     404: "Not found",
 *     500: "Internal Server Error"
 * }
 *
 **/
router.get("/person/name", async (req, res, next) => {

    return res.json({
        name: "John Doe"
    })

});

module.exports = router;

VisualBoost

The analyzed extension after exectuing synchronization

The example above demonstrates how to set up an extension. The main difference from a standard express route are the annotations within the comment block. These annotations help analyze the route during the synchronization process. Once analyzed, the route is integrated into the software architecture in VisualBoost. This ensures the architecture remains complete, even with custom business logic. Additionally, this feature can be reused for creating interface documentation and generating client code.

Annotations

VisualBoost provides 4 different annotations:

Annotation	Description	Available in HTTP Method
@name:	The functions name.	GET, POST, PUT, DELETE
@body:	The request body of the route.	POST, PUT, DELETE
@return:	The response body of the route.	GET, POST, PUT, DELETE
@errors:	The errors that can be thrown by the route.	GET, POST, PUT, DELETE

Annotation values

The annotations @body and @return can be used to define the request and response bodies of a route. The following data types are supported:

Type	Description	Example
Boolean	Send or return a single boolean value	@return: Boolean
Int	Send or return a single integer value	@return: Int
Float	Send or return a single float value	@return: Float
String	Send or return a single string value	@return: Stringation
Date	Send or return a single date value	@return: Date
Location	Send or return a single location value (array with latitude and longitude)	@return: Location
Enumeration	Send or return a single enumeration value. The structure of the Enum annotation is represented as ENUM_NAME(VALUE1, VALUE2, ...).	@return: Gender(MALE, FEMALE)
Object	Send or return a single object	@return: { name: String, age: Int, address: { housenumber: Int, street: String, location: Location } }
Array	Send or return multiple values	Return an array of objects: @return: [{ name: String, age: Int, address: { housenumber: Int, street: String, location: Location } }] Return an array of strings: @return: [String]

The annotation for @errors requires the following structure:

@errors: {
     <http_status_1>: "<error_message_1>,
     <http_status_1>: "<error_message_2>
 }

Example:

@errors: {
    400: "Bad Request",
    404: "Not found",
    500: "Internal Server Error"
}

Be sure that the last error message does not end with a comma. If it does, the synchronization process may produce incorrect results.