Description annotation

Adds a documentation text to each API Object method.

Syntax

 '['Description("<text>")']'

View Syntax conventions

Where:

text
Method and parameter descriptions.

Description

The Description annotation is introduced to enrich the documentation of each method within the API object, which may contain several methods performing different tasks or actions.

The purpose of this annotation is to provide brief descriptions that contextualize the function of each method, explaining its purpose and how it should be implemented.

This documentation is useful for OpenAPI generation by providing applications that import or parse this file with a deeper understanding of each method. Consequently, it facilitates a more accurate use of API calls, improving integration and efficiency in application development.

Sample

For the examples taken from sample, the Description annotation is used to provide a concise and enlightening description of the functionality of each method in the APIAccount API object.

Sample #1

APIAccount {
         [Description("Provides access to account information, allowing querying of account status and owner.")]
         AccountInfo(in:&AccountId, in:&AccountPassword, out:&AccountStatus, out:&AccountOwner)
         => QueryAccount(&AccountId, &AccountPassword, &AccountOwner, &AccountStatus);
         }

Sample #2

APIAccount{
         [Description("Retrieves the account status based on the provided account number and password.")]
         AccountInfo(in:&AccountId, in:&AccountPassword, out:&AccountStatus)
         => QueryAccount(&AccountId, &AccountPassword, &AccountOwner, &AccountStatus);
         }

Sample #3

APIAccount{
         [Description("Retrieves the account status with a predefined account owner.")]
         AccountInfo(in:&AccountId, in:&AccountPassword, out:&AccountStatus)
         => QueryAccount(&AccountId, &AccountPassword, "Tomas Huck", &AccountStatus);
        }

Availability

This annotation is available since GeneXus 18 Upgrade 7.