WSTags

Assign one or more tags to a REST operation. The value corresponds to the "tags" keyword in the OpenAPI specification and is used for grouping and documentation.

Syntax

WSTags = "{ tag } [,...]"

Where WSTags is a comma-separated list of string values, and:

tag defines a tag of the operation.

WSTags is an optional attribute.

Usage

You set the WSTags attribute in the ATTRIBUTES() clause of the function. Tags are used for grouping, filtering, and documentation, such as in OpenAPI output or API explorer tools.

Each tag is a string and must not include characters such as commas or brackets. For more details about tag grouping in OpenAPI, refer to theOpenAPI documentation (external link).

Example: Assigning a single tag

FUNCTION getCustomer(id INTEGER ATTRIBUTE(WSParam))
ATTRIBUTES(WSGet,
WSPath = "/customer/{id}",
WSTags = "Customer")
RETURNS RECORD (id INTEGER, name STRING)
ATTRIBUTES(WSName = "Customer")
#...
END FUNCTION

Example: Assigning multiple tags

FUNCTION updateOrder(id INTEGER ATTRIBUTE(WSParam))
ATTRIBUTES(WSPut,
WSPath = "/order/{id}",
WSTags = "Order, Admin, Internal")
RETURNS (INTEGER)
#...
END FUNCTION

OpenAPI output example

paths:
/customer/{id}:
get:
tags:
- Customer
responses:
'200':
description: successful operation

Benefits

Allows you to categorize and group operations in the OpenAPI document.
Improves readability in OpenAPI tools, where operations appear under their assigned tags.
When using fglrestful, the tags appear in the client function headers to identify the logical grouping of each function.

Compilation rules

Scope: WSTags applies only to functions exposed as web services.
Accepted values: One or more strings in a comma-separated list:
```
ATTRIBUTES(WSTags = "Customer, Admin")
```
Requires a value.

GWS engine

The GWS engine exports the tags to the OpenAPI document under the tags keyword. The tags are used only for documentation and client-generation purposes.

Global tags generation

All tag names defined with the WSTags attribute across the service are collected and generated in the OpenAPI document’s global tags section. Each tag name appears only once in that section.

Case sensitivity

The tags keyword is case-sensitive in the OpenAPI specification. For example, Users and users are considered distinct tags.

Generated fields

By default, only the name field is generated for each tag in the global tags array.

Customization

If additional fields such as a tag description are required, you can customize the generated OpenAPI document by registering a callback with com.WebServiceEngine.RegisterRestOpenAPIHandler. This allows you to add extended metadata to the OpenAPI global tags section.

The output shown in this example is from the Firefox™ browser, which formats JSON for readability. The appearance may vary depending on your browser.

Images shows OpenAPI documentation with global tags — Figure: Example (OpenAPI excerpt) global tags generated by the GWS engine

fglrestful

fglrestful uses the defined tags when generating the client code. The tags appear in the client function header as comments, helping you understand the logical grouping of each function.