Generate service description on demand

The OpenAPI description provides information about the operations defined in a web service.

You can output the OpenAPI description from the URL of the web service in a browser. For details, go to Generate service description on demand (OpenAPI).

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, scopes, and so on. 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. The output shown is from the Firefox® browser, which converts JSON to human readable format. The output may vary depending on your browser.

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


Paths

The paths section lists URI paths for the web service, and each path (for example, /v3/echos/none/{nb}, /v3/prices/{nb}) can have operations associated with different HTTP verbs (GET, POST, and so on).
Figure: Resource paths with versioning

OpenAPI description showing paths prefixed with version identifier
Figure 2 shows the components of an operation:
  • The URI path (/v3/prices/{nb}). As operations are versioned by URI in this web service, the version identifier ("/v3") is displayed as a prefix to the resource path. To read more about versioning, go to Specify version mode.

    The OpenAPI specification denotes path templates within curly braces ({ }), and the /{nb} path section of the URI will be substituted with an actual value when a GWS client makes a call to the resource.

  • The HTTP verb (get).
  • The parameters. (Parameters are described in Parameters)

Parameters

The parameter section lists the input and output parameters for the operation.
Figure: Parameters represented in the OpenAPI description

Parameters in the OpenAPI description, highlighting version query parameter
Figure 3 shows the parameters of the operation:
  • A query parameter for the version (api-version) is listed. The version identifier is displayed in the value of the enum keyword as shown. To read more about versioning, go to Specify version mode.
  • A path parameter is listed that denotes the /{nb} path section of the URI, which will be substituted with an actual value when a GWS client makes a call to the resource.
  • A return parameter is listed under the responses section of the operation.

Body requests and responses

POST and PUT HTTP requests usually contain a request body for the payload you want to send to the server. Typically, this will be JSON encoded string.

The OpenAPI specification denotes data types, such as records and arrays, based on how you define variables in the input and output parameters of functions in your Genero BDL code:
  • If you set WSMedia for application/xml as the content type, or the object type is not named in the Genero BDL code (an anonymous or unknown type), the GWS engine exposes the object content like this:
    • For the request, objects are defined in properties of the schema of the requestBody section.
    • For the response, objects are defined in the content section of the responses section.
  • If you set WSMedia for application/json (the default) and objects are defined as types (named types) in the Genero BDL code, the GWS engine outputs the type as a reference ($ref) like this:
    • For the request, the $ref is defined in a schema of the requestBody section.
    • For the response, the $ref is defined in the content of the responses section.
    The $ref uses an XPath expression to locate where in the components/schemas section of the OpenAPI description the properties are exposed. This named type may be referenced in several resources but only has its properties exposed once.

For information on how Genero BDL data types are mapped in OpenAPI, go to OpenAPI types mapping: BDL.

Figure: Anonymous type (exposed)

Anonymous type exposes the object content when the data type is XML
Figure 4 shows the operation response is set for application/xml as the content type; therefore, the GWS engine exposes the object content (properties) in the schema.
Figure: Named type ($ref)

A named type references the content in a component schema
Figure 5 shows the operation response is set for application/json (the default) on a named content type; therefore, the GWS engine outputs the type as a reference ($ref) in the schema.
Important: Reference definition ($ref) does not affect headers

A reference definition ($ref) is only allowed in named types used on a body with a JSON schema. For example, if you set the types for error handling (with WSError attribute) for application/json (the default), the GWS engine outputs the type as a reference ($ref) in the responses section. Parameters like WSHeader, WSQuery, or WSCookies are not affected.

If the GWS detects the same type name (for example,"recType" in Figure 5) is used for another type, error 15580 is raised.

For a more in-depth understanding of the different parts of OpenAPI descriptions, refer to the OpenAPI documentation.