Module:OpenAPI

Contents 1 Introduction 2 API Generation 2.1 Defining the API 2.1.1 Static API definition 2.1.2 Dynamic API definition 2.1.3 Setting the Openbravo server 2.2 Deploying the API 2.3 Visualizing the API

Introduction

This module allows to integrate in Openbravo APIs documented using the OpenAPI specification. It also provides the ability to visualize and interact with those APIs through Swagger-UI.

API Generation

Defining the API

APIs can be defined either in an statically or dynamically.

Static API definition

Static APIs are those that are directly created in a manual way, i.e., by creating a template file with the API manually. The steps to define an static API are:

1. Create a JSON (.json) or yaml file (.yml) template file following the OpenAPI specification. See here for a detailed explanation of how to create the file. This files is a template because it can contain placeholders like ${contextURL} that will be resolved when the api is requested. See here for additional information.
2. Place that file under a folder named api of your module.

See an API definition example here.

Dynamic API definition

Those modules that want to document their APIs in a dynamic way, i.e., without the need of creating and maintaining manually a template file with the API information, should follow this approach.

To generate an API in a dynamic way a class extending OpenAPIProcessor must be created.

 
import java.io.IOException;
import java.io.InputStream;
import java.util.Set;
 
import org.openbravo.service.openapi.provider.OpenAPIProcessor;
 
public class DynamicAPIGenerator extends OpenAPIProcessor {
 
  @Override
  protected Set<String> getAPINames() {
    // return the names of the APIs generated with this processor
  }
 
  @Override
  protected InputStream getAPIStream(String apiName) throws IOException {
    // generate the stream for the given API
  }
}

The two methods to be implemented are:

• getAPINames: returns a String with the names of the different APIs that can be generated by the class.
• getAPIStream: returns the InputStream with the data containing the definition of the API whose name is received as parameter.

For example the Openbravo Business API module generates its API documentation automatically using this mechanism, by reading the application dictionary definitions of the different endpoints. See here to see how it is implemented.

Setting the Openbravo server

One of the configuration properties of the OpenAPI specification file is the server which provides connectivity information to a target server that allows to interact with the API.

The OpenAPI module makes it possible to configure this property dynamically, so that it is set with the value of the context.url property of the Openbravo.properties file. This way we will be able to interact with the API using the Openbravo server itself. To define this setting in such way, the ${contextURL} placeholder should be used:

...
servers:
- url: ${contextURL}
...

That placeholder will be replaced with the context.url when the API is requested.

Deploying the API

The APIs are deployed at compile time. To deploy them, the following steps should be done:

1. Move to the sourcepath/modules/org.openbravo.service.openapi module
2. Run ant compile.api
3. Go back to the sourcepath folder
4. Run ant smartbuild

Visualizing the API

Once the APIs have been deployed, they can be visualized at the following URL:

http(s)://<openbravo_url>/api

A live example is available here.