Generate service description on demand

Access a description of a REST Web service through a query string on the URL of the Web service.

You can output the OpenAPI description for the Web service in a browser tab in either JSON or YAML format. For a web service server started with Genero Application Server (GAS) the OpenAPI description URL would be:

http://myServer:myPort/gas/ws/r/myGroup/myXcf/myService?openapi.json

Or

http://myServer:myPort/gas/ws/r/myGroup/myXcf/myService?openapi.yaml
Warning:

The feature for generating the OpenAPI documentation in YAML format is experimental and may change.

To generate the OpenAPI documentation for a specific version of operations, add the "&version=version_name" query string to the URI:

http://myServer:myPort/gas/ws/r/myXcf/myService?openapi.json&version=v3

The GWS service must be running in order to provide the output.

The OpenAPI description provides information about the operations defined in a Web service. When developing client applications that access Web services, you may need to refer to the OpenAPI description for the Web service for details of the resource endpoints, operations, supported media types, version, etc. To learn more about the OpenAPI specification, refer to the OpenAPI documentation.

The sections highlighted in this topic are valuable in respect to Genero RESTful Web services. The samples are in JSON format.

Service information

The OpenAPI description includes basic service information provided, such as the title of your Web service, the version, and contact information.
Figure: Sample of service information in OpenAPI description file


Paths

The paths section lists the paths to resources (for example, /add, /sub/{f}, /mult/{coef}/hello, and so on) and the HTTP verb (GET, POST, and so on) used by operations. If operations are versioned by URI, the path will also include information about the version. The version identified is displayed as a prefix to the resource path. For example, "/v3" is the version identifier for operations shown in Figure 2.
Figure: Resource paths with versioning

OpenAPI description showing paths prefixed with version identifier

Parameters

The paths section identifies the input and output parameters for each function. If operations are versioned by query or header, parameters for the version are included. The version identifier is displayed in the value of the enum keyword as shown in Figure 3. To read more about versioning, see Specify version mode.
Figure: Parameters represented in the OpenAPI description file

Parameters in the OpenAPI description, highlighting version query parameter

Body requests and responses

Data types (such as records and arrays) used on the body request or response are shown based on how the content type is specified by WSMedia and whether objects are defined as types (named types) in the Genero BDL code.
  • If WSMedia is set for application/xml as the content type, or the object type is not named (an anonymous or unknown type), the GWS engine exposes the object content (properties) in the schema sub part.
    Figure: Anonymous type (exposed)

    Anonymous type exposes the object content when the data type is XML
  • If WSMedia is set for application/json (the default) on a named content type, the GWS engine outputs the type as a reference ($ref) in a schema sub part.
    The reference uses an XPath expression to locate where in the components/schemas section the properties are exposed. This named type may be referenced in several resources but only has its properties exposed once.
    Important: Reference to definition ($ref)

    A reference definition ($ref) is only allowed in named types used on a body with a JSON schema and error handling types (for example, using WSError attribute). Parameters like WSHeader, WSQuery, or WSCookies are not affected.

    Figure: Named type ($ref)

    A named type references the content in a component schema
    If the GWS detects the same type name (for example,"recType" in Figure 5) is used for another type, error 15580 is raised.

Responses

Responses, such as error handling information, error codes and messages are shown in the responses section. If the types for error handling (for example, using WSError attribute) are set for application/json (the default), the GWS engine outputs the type as a reference ($ref) in the responses sub parts. The reference will use an XPath expression to point to where in components/responses section the properties are exposed.
Figure: Responses