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://myhost:6394/gas/ws/r/myGroup/myXcf/myService?openapi.json

Or

http://myhost:6394/gas/ws/r/myGroup/myXcf/myService?openapi.yaml
Warning: The feature for generating the OpenAPI specification in YAML format is experimental and may change.

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, 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

Service information section

Paths

The paths section lists the available resources and functions (for example, /add, /sub/{f}, /mult/{coef}/hello, etc.) and operations (GET, POST, etc.).

Parameters

The paths section identifies the parameters, input and output, for each function.
Figure: Parameters represented in the OpenAPI description file

Details of parameters are shown with their properties of type and format

Body requests and responses

Data types (such as records and arrays) used on the body request or response on the server side are shown based on how the content type is specified by WSMedia on the server side. The GWS engine exposes the object content (properties) in the schema sub parts.
Figure: Anonymous type (exposed)

Anonymous type exposes the object content showing its properties

Responses

Responses, such as error handling specifications, error codes and messages are shown in the responses section.
Figure: Responses

Responses section shows content for error handling