Service annotation

Streams 5.5.1 or later The SPL annotation @service provides documentation to augment generated API documentation for the application service that is associated with an IBM® Streams job.

Read syntax diagramSkip visual syntax diagram@service

The @autonomous annotation can be applied only to the main composite of a Streams application. This annotation is optional and is not required to enable the application service support. It is often used in conjunction with the @endpoint annotation to provide overarching documentation on a collection of endpoints that are exposed by an application.

For more information about Streams application services , Enabling Streams application services

The SPL compiler reports errors when an @service annotation is applied in the following situations:
  • When @service is placed on any operator that is not the application main composite.
  • When JSON validation fails on any parameters that require JSON object content.

Optional elements

title
A short title for the API set. The type of the parameter is rstring.
externalDocsURL
A URL to additional documentation for the API set. The type of the parameter is rstring.
externalDocsDescription
A short description of the target documentation that is referenced by the externalDocsUrl parameter. The type of the parameter is rstring.
tags
A set of tags that can be used to logically group APIs. The type of the parameter is rstring. The format of the value is a JSON object with embedded quotes escaped. Each object property name specifies a tag name. The corresponding property value is a JSON object that contains tag metadata. The following metadata properties are supported:
  • description: A short description of the tag grouping. The type of the parameter is rstring.
  • externalDocs: Information about external documentation that is related to the tag grouping. The type of the parameter is object. The following properties are supported:
    • url: A URL to additional documentation for the tag. The type of the parameter is rstring.
    • description: A short description of the target documentation that is referenced by the url parameter. The type of the parameter is rstring.
description
A short description of the API set. The type of the parameter is rstring.
version
The version of the API document.

For more information about these parameters, see the OpenAPI Specification with a focus on the descriptions of the OpenAPI, Info, and External Documentation objects.

Example

Provide customized API documentation for a Streams stock quote application service:
@service (title="Stock Quote Service", 
          externalDocsUrl="https://mycompany.com/stockapp/doc", 
          externalDocsDescription="Stock quote service documentation", 
          tags="{\"Input\": {
                    \"description\": \"Endpoints for inserting data.\",
                    \"externalDocs\": {
                      \"url\": \"https://mycompany.com/stockapp/input/doc\",
                      \"description\": \"Documentation for inserting data.\"         
                    }
                 },
                 \"Output\" : {
                    \"description\": \"Endpoints for retrieving data.\",
                    \"externalDocs\": {
                      \"url\": \"https://mycompany.com/stockapp/output/doc\",
                      \"description\": \"Documentation for retrieving data.\"         
                    }
                  }
                }",
          description="This service ingests stock quote data and retrieves ticker averages over time.",
          version = "1.0.0.0")