WSTags

The WSTags attribute allows you to assign one or more tags to a REST operation. It 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, each representing a tag and where:

tag defines a tag of the operation.

WSTags is an optional attribute.

Usage

The WSTags attribute is used to assign one or more tags to a RESTful web service operation. These tags are typically used for grouping, filtering, or documentation purposes, such as in OpenAPI documentation generation or API explorer tools.

You set the WSTags attribute in the ATTRIBUTES() clause of the function. Tags should be meaningful for grouping operations. Tags can be used to organize endpoints by business domain, access level, or any other logical grouping.

Tags are exported to the OpenAPI documentation and can be used by tools to group or filter endpoints. Each tag should be a valid string and must not contain special characters such as commas or brackets. For more information, refer to Swagger: Grouping Operations with Tags (external link).

Example 1: 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 2: 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

Makes it possible to categorize and group operations in the OpenAPI document.
Improves readability in tools such as OpenAPI document, where operations are displayed under their assigned tags.
When using fglrestful, the tags are also generated in the client function headers, helping developers quickly identify the logical grouping of each function.

Compilation rules

Scope: WSTags applies only to functions exposed via web services.
Accepted values: One or more strings. Multiple tags must be declared 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, which is an array of strings. At runtime, the tags have no functional effect: they serve documentation and client-generation purposes only.

fglrestful

fglrestful takes into account the tags when generating the client code. The defined tags are added as comments in the function header to help developers quickly understand the logical grouping of each client function.