Documenting RestFul services

Official Content

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

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

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>

Note

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

See Also

Open API Initiative



Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.