Understanding the OpenAPI description of a Genero RESTful service
The OpenAPI description provides a structured view of your RESTful web service, including service information, paths, parameters, and the request and response bodies generated from your Genero BDL code.
When you deploy a RESTful web service with GWS, the engine generates an OpenAPI description that reflects the structure of your service. This description includes the resource paths exposed by the service, the operations supported for each path, the parameters required by those operations, and the formats used for request and response bodies.
You can retrieve the OpenAPI description by accessing the service URL in a browser. The description is provided in JSON format and can be viewed using any standard web browser or API tool. The examples in this topic use the JSON view provided by Firefox, which formats the output in a readable, structured style.
This topic introduces the main sections of the OpenAPI description generated by GWS and highlights how they relate to your Genero BDL code.
Service information
The service information section provides high‑level metadata, including the service title, version, and optional contact information. These values originate from the attributes defined for your RESTful service.
Paths
The paths section lists each resource path in your service. Each path includes the HTTP
operations supported by the resource. Path templates appear with variables enclosed in braces, such
as {id}, which indicate values that the client supplies when calling the operation.
If your service uses URI‑based versioning, such as /v3/orders, the version prefix appears in the path. This allows you to expose multiple versions of the same resource in parallel.
Parameters
The parameters section lists the inputs the client must provide when invoking an operation. These
include path parameters that replace variables in the URI, and query parameters such as
api-version or other operation‑specific values.
The OpenAPI description also shows response information, including the return status and any body content defined for successful or error responses.
Request and response bodies
POST and PUT operations usually include a request body. The
OpenAPI description represents these bodies according to the data types defined in your Genero BDL
code. The engine maps these types into JSON schema definitions so that client tools can understand
the structure of the payload.
Response bodies follow the same mapping rules. The OpenAPI description shows the type of data returned by each operation, including structured objects and arrays.
Further information
For a complete explanation of the OpenAPI specification itself, refer to the OpenAPI (external link) documentation. The intent of this topic is to describe how the GWS engine presents your Genero RESTful service in the OpenAPI format.