Documenting RestFul services

Official Content
This documentation is valid for:

RESTful applications are widely used in different kinds of solutions because they are simple, lightweight, and fast. As a consequence, there's an obvious need that the service providers and consumers converge on how to describe the REST APIs. They are very similar to the already standardized WSDL for SOAP web services.

In this case, Swagger is a solution for solving the standardization problem of REST APIs. Therefore, consumers of RestFul services use Swagger as a standardized way of interacting with Rest APIs. 

What is Swagger?

Swagger is a basis for describing REST APIs.

It defines a standard interface to REST APIs (it's a specification or representation in YAML or JSON format) which allows humans and computers to discover and understand the capabilities of the service without the need of network traffic inspection or any kind of guesswork.

How to document Restful services in GeneXus

Configure the Generate OpenAPI interface property to TRUE. Afterward, all the Rest web services in GeneXus will have their documentation in a file called default.yaml, located under the application directory. The file can be accessed as follows: http://<server>/<virtual_dir>/default.yaml when .NET/NetCore generators are used and http://<server>/<virtual_dir>/static/default.yaml when Java generator is used

The default.yaml file is updated when any of these objects is generated


HTTP Access Control (CORS) has to be enabled on the server so that the server can accept HTTP requests from the server.

NET generator

Add the following HTTP headers through the IIS manager:

Name:Access-Control-Allow-Headers  Value:Origin, X-Requested-With, Content-Type, Accept
Name:Access-Control-Allow-Origin     Value:

Java generator

Add the following filter in the web.xml file:

            <param-value>Origin,X-Requested-With,Content-Type, Accept</param-value>


The swagger documentation can be interpreted using the OpenAPI import tool.

See Also

Open API Initiative