View source | Discuss this page | Page history | Printable version   

Module:OpenAPI

Contents

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.

Bulbgraph.png   This feature is available starting from 3.0PR19Q3.

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.
Bulbgraph.png   It is recommended to follow this naming convention to avoid collisions when defining multiple APIs: modulepackage-apiname.yml.

See an API definition example here.

Dynamic API definition

Bulbgraph.png   This features is available starting from version 1.1.0

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:

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

Bulbgraph.png   Starting from version 1.1.0 of the OpenAPI module, the APIs are deployed automatically, so the tasks presented in this section are no longer needed.

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
API Visualization


A live example is available here.

Retrieved from "http://wiki.openbravo.com/wiki/Module:OpenAPI"

This page has been accessed 2,697 times. This page was last modified on 18 February 2022, at 07:06. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.