Creating REST API servers with TMS XData is a breeze and it's even easier to generate documentation for it. XData automatically creates an OpenAPI document that describes your API, and automatically provides a SwaggerUI web interface for you that lists all your endpoints, input parameters, output responses, and allows you to test the API directly from the web. That has been available for a while.

Now, with the latest version released this week, XData also supports Redoc.

Redoc is an open-source tool that generates a full documentation for your API. It has many intersections with SwaggerUI, but I consider the latter more "test-oriented", while the former is more "documentation-oriented".

In other words, SwaggerUI makes it easy for you to check your available endpoints, see how to invoke them, and effectively invoke them from the web interface.

Redoc, on the other side, doesn't have an option for you to invoke endpoints. Its focus is to list the endpoints, parameters, input and output, in the nicest way possible. It's a much better option (in my opinion) to provide the users of your API with a professional-looking documentation. In any case, whatever you prefer, both are available in XData.

Enabling Redoc

Enabling Redoc support in your server is just a matter of setting the property RedocOptions.Enabled to true in your TXDataServer component, either in object inspector or from code:

XDataServer1.RedocOptions.Enabled := True;

Using Redoc

Once enabled, Redoc will be available from the address /redoc relative to your server base path. Just open your browser and go to the address:

http://server:2001/tms/xdata/redoc

It will display an interface like this:

Configuring Redoc

The Redoc interface can also be configured using the RedocOptions property of either TXDataServer orTXDataServerModule.

You can use CustomParams property to set any Redoc parameter and its value. You can refer to Redoc documentation for the full list of parameters.

For example:

XDataServer1.RedocOptions.CustomParams.Values['disable-search'] := 'true';

Using tag groups

Redoc also supports the concept of tag groups.

It's an even higher level than tags, where you can group tags under a common name. To "put" a tag in a specific tag group use the swagger XML tag with the tag-group attribute:

  /// <swagger name="tag-group">Customers</swagger>
  /// <swagger name="tag-name">Customer Authentication</swagger>
  /// <swagger name="tag-description">Endpoints for authenticating customers</swagger>
  ICustomerAuthenticationService = interface(IInvokable)

Endpoints declared in the above interface will be under tag "Customer Authentication", which in turn will be under tag group "Customers":

Automatic validation rules

Another nice new feature is the automatic addition of validation rules to the OpenAPI document. Note this is not limited to Redoc only.

If you use some validation attributes in your classes, like Range, MinLength or MaxLength, such rules are automatically included in the OpenAPI document. For example, suppose you have a DTO class declared like this and used as an input for and endpoint (other properties removed for clarity):

  [Entity, Automapping]
  TTrack = class
  strict private
    [Required, MaxLength(150)]
    FName: string;
    [Range(0, 4800000)]
    FMilliseconds: Nullable<integer>;

The OpenAPI document will include the properties with maxLength and minimum/maximum properties:

"MusicEntities.TTrack": {
    "properties": {
        "Name": {
            "type": "string",
            "maxLength": 150,
            "x-data-type": "String",
            "x-length": 255
        },
        "Milliseconds": {
            "type": "integer",
            "maximum": 4800000,
            "minimum": 0,
            "x-data-type": "Int32"
        }
    }

Such information will of course be used by the OpenAPI tools you might use. For example, the final Redoc documentation will nicely show the restrictions of such properties:

Other nice new additions

This new update also provides nice features in other TMS BIZ products. First, all of them now support the new ARM64 compiler for macOS and iOS Simulator.

TMS Logging includes a new Discord output handler, allowing your log messages to be output to a Discord channel via web hooks.

TMS Aurelius projections are now being used also for many-valued associations, i.e., now you can specify the properties you want to load not only for the entities and its associations, but also for sublists. This gives you freedom and the possibility to increase the performance of list-loading by an order of magnitude, depending on the situation.

There are also some minor additions to TMS Sphinx and TMS Sparkle. 

I hope you have enjoyed the latest features as much as I do. And stay tuned: a major new addition is coming! TMS Smart Setup will enter the beta phase. In case you don't now yet, it's a new way to install TMS products - initially available for TMS BIZ and TMS Flexcel - that will improve the experience if installing and updating TMS products. If you are curious, keep an eye in your e-mail inbox and our social media, we will announce it soon!