Documenting RESTFul services

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. 

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 Framework/ .NET 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

• Procedures as Rest Web Services in GeneXus
• Data Providers as Rest Web Services in GeneXus
• Business Components as Rest web services in GeneXus

Requirements 

HTTP Access Control (CORS) has to be enabled on the server so that the server can accept HTTP requests from the swagger.io 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:http://editor.swagger.io

Java generator

Add the following filter in the web.xml file:

    <filter>
        <filter-name>CorsFilter</filter-name>
        <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
        <init-param>
            <param-name>cors.allowed.origins</param-name>
            <param-value>http://editor.swagger.io,https://editor.swagger.io</param-value>
        </init-param>
        <init-param>
            <param-name>cors.allowed.methods</param-name>
            <param-value>GET,POST,HEAD,OPTIONS,PUT</param-value>
        </init-param>
        <init-param>
            <param-name>cors.allowed.headers</param-name>
            <param-value>Origin,X-Requested-With,Content-Type, Accept</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>CorsFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

See Also

Open API Initiative