Show/Hide Toolbars

TMS XData Documentation

Navigation: Basic XData Programming

OpenAPI/Swagger Support

Scroll Prev Top Next More

The XData server can optionally provide a JSON file containing the OpenAPI Specification (OAS, formerly Swagger) for your whole server API. This opens up a lot of possibilities; usage of several tools of the OpenAPI ecosystem is possible. The main one is Swagger UI: It is web front-end to describe and test your API.

 

Enabling support for OpenAPI (Swagger)

 

To enable OpenAPI support in your server, just set the property SwaggerOptions.Enabled to true in your TXDataServer component, either in object inspector or from code:

 

XDataServer1.SwaggerOptions.Enabled := True;

 

Alternatively, if you are using TXDataServerModule instead, you can just use the unit XData.OpenAPI.Service and call the method RegisterOpenAPIService anywhere in your server application:

 

uses {...}, XData.OpenAPI.Service;
 
{...}
  RegisterOpenAPIService;

 

Retrieving the OpenAPI Specification (OAS) file

 

The OAS file is available through a GET request to the URL "/openapi/swagger.json" relative to your server root URL. For example, if your server root is http://server:2001/tms/xdata/, then you will be able to access the file from this URL:

 

GET http://server:2001/tms/xdata/openapi/swagger.json

 

Enabling Swagger UI

 

XData server can optionally publish and endpoint to provide a SwaggerUI web-based interface that works as both a full documentation of your API as well a test interface. Swagger UI is a web-based front-end to dynamically document and test your API. Quoting their their website: "Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your Swagger specification, with the visual documentation making it easy for back end implementation and client side consumption.".

 

To enable SwaggerUI support in your server, just set the property SwaggerUIOptions.Enabled to true in your TXDataServer component, either in object inspector or from code:

 

XDataServer1.SwaggerUIOptions.Enabled := True;

 

Alternatively, if you are using TXDataServerModule instead, you can just use the unit XData.SwaggeUI.Service and call the method RegisterSwaggerUIService anywhere in your server application:

 

uses {...}, XData.SwaggerUI.Service;
 
{...}
  RegisterSwaggerUIService;

 

Using SwaggerUI

 

Once enabled, SwaggerUI is available in the address "/swaggerui" relative to your server base path. Just open your browser and go to the address:

 

http://server:2001/tms/xdata/swaggerui

 

It will display an interface like this:

 

xdata_swaggerui

 

 

Configuring Swagger (OpenAPI Specification)

 

For the Swagger specification, you can use SwaggerOptions property of either TXDataServer or TXDataServerModule to configure the specification returned by the server:

 

XDataModule.SwaggerOptions.AuthMode := TSwaggerAuthMode.Jwt;

 

Only available property is AuthMode and options are TSwaggerAuthMode.Jwt or None. When Jwt is enabled, a new security definition named jwt requiring an Authorization header will be added to all requests.

 

You can also configure the specification by passing parameters in the query part of the URL, and they can be one of the following:

 

Name

Description

ExcludeEntities

Boolean parameter. Default is False. When True, the specification will not contain the automatic CRUD operations on entities provided automatically by XData (entity resources).

 

Example:

/openapi/swagger.json?ExcludeEntities=True

ExcludeOperations

Boolean parameter. Default is False. When True, the specification will not contain any service operations.

 

Example:

/openapi/swagger.json?ExcludeOperations=True

AuthMode

String parameter. Options are "none" and "jwt". When jwt is specified, a new security definition named jwt requiring an Authorization header will be added to all requests.

 

Example

/openapi/swagger.json?authmode=jwt

 

 

Configuring SwaggerUI

 

The SwaggerUI interface can also be configured using the SwaggerUIOptions property of either TXDataServer or TXDataServerModule. Available properties are:

 

 

Name

Description

ShowFilter

Boolean parameter. Default is False. When True, the SwaggerUI will display a filter edit box to search for API operations.

DocExpansion

Enumerated parameter. Specifies the default expand level of the listed API operations. Valid values are:

 

TSwaggerUIExpansion = (List, None, Full);

 

Default value is List;

 

Examples:

 

XDataModule.SwaggerUIOptions.Filter := True;
XDataModule.SwaggerUIOptions.DocExpansion := TSwaggerUIExpansion.None;