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.
![]() | 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:
- 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.
- Place that file under a folder named api of your module.
![]() | 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
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
![]() | 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:
- Move to the sourcepath/modules/org.openbravo.service.openapi module
- Run ant compile.api
- Go back to the sourcepath folder
- 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.