This documentation is now part of the ovirt-engine-api-model repository,
find it here:
https://github.com/oVirt/ovirt-engine-api-model
This document describes how to contribute reference documentation for the API.
The specification of the API is written using Java as the supporting language.
Data types are represented by Java interfaces. For example, the Vm.java
file contains the specification of the Vm entity, which looks like
this:
@Type
public interface Vm extends VmBase {
String stopReason();
Date startTime();
Date stopTime();
...
}The methods of these interfaces represent the attributes of the data types, including their type and name.
Services API are also represented by Java interfaces. For example, the
VmService.java file contains the specification of the Vm service, and
it has content similar to this:
@Service
public interface VmService extends MeasurableService {
interface Start {
@In Boolean pause();
@In Vm vm();
@In Boolean useCloudInit();
@In Boolean useSysprep();
@In Boolean async();
}
...
}Operations are represented as nested interfaces. The names of these nested interfaces correspond to the names of the operations, and the methods correspond to the parameters of the operations.
The Java language supports adding documentation in the code itself, using the
Javadoc comments. These comments start with /** and end with */ and can
be added before the definition of any element, like interfaces and methods. These
Javadoc comments are the mechanism that we use to document the specification. For
example, the Vm type can be documented modifying the Vm.java file like this:
/**
* Represents a virtual machine.
*/
@Type
public interface Vm extends VmBase {
...
}Attributes can be documented in a similar way, just placing the Javadoc comment before the definition of the method that represents that attribute:
/**
* Represents a virtual machine.
*/
@Type
public interface Vm extends VmBase {
/**
* Contains the reason why this virtual machine was stopped. This reason is
* provided by the user, via the GUI or via the API.
*/
String stopReason();
...
}Same for services, their operations and their parameters:
/**
* This service manages a specific virtual machine.
*/
@Service
public interface VmService extends MeasurableService {
/**
* This operation will start the virtual machine managed by this
* service, if it isn't already running.
*/
interface Start {
/**
* Specifies if the virtual machine should be started in pause
* mode. It is an optional parameter, if not given then the
* virtual machine will be started normally.
*/
@In Boolean pause();
...
}
...
}These Javadoc comments are processed by tools that are part of the system and it is used to automatically generate the reference documentation. You can see an example of the generated documentation here.
This documentation viewer will eventually be part of the oVirt Engine server itself.
The Javadoc comments have their own format, but it isn't used by the
our documentation tools. Instead of that the tools expect and support
Markdown, in particular the
GitHub
variant. This means that Javadoc comments can contain rich text and
examples. For example, you could write the following to better describe
the Start operation of the Vm service:
/**
* Specifies if the virtual machine should be started in pause
* mode. It is an _optional_ parameter, if not given then the
* virtual machine will be started normally.
*
* To use this parameter with the Python SDK you can use the
* following code snippet:
*
* ` ` `python
* # Find the virtual machine:
* vm = api.vms.get(name="myvm")
*
* # Start the virtual machine paused:
* vm.start(
* params.Action(
* pause=True
* )
* )
* ` ` `
*/
@In Boolean pause();The mechanism to contribute documentation is to modify the .java source
files. This source code is part of the ovirt-engine project, which is
hosted in gerrit.ovirt.org. So the
first step to be able to contribute is to register to that system and
prepare your environment for using git. For details see
this.
To summarize, once you have registered and prepared your system to
use git, this is the command that you need to execute in order to
clone the ovirt-engine source:
$ git clone gerrit.ovirt.org:ovirt-engine
The model source files are all inside the backend/manager/modules/restapi/model
directory. For documentation purposes the most relevant files are the .java
source files, which are inside the src/main/java directory. So you will
probably want to change to that directory:
$ cd backend/manager/modules/restapi/model
$ cd src/main/java
This directory contains two sub-directories: types and services. The first
is for the specifications of data types and the second for the specifications
of services.
Files are named like the entities, so they should be easy to locate.
You can use your favorite editor to modify the source files. Just make sure to modify only the Javadoc comments.
Once you are happy with the changes that you made to the documentation you
can prepare and submit a patch. For example, lets assume that you have
modified the Vm.java file, this is what you will need to do to submit
the patch:
$ git add types/Vm.java
$ git commit -s
This will open an editor where you can write the commit message. By default
it will probaby be vim, but you can change it with the EDITOR environment
variable:
$ export EDITOR=my-favorite-editor
$ git add types/Vm.java
$ git commit -s
In that editor you will be asked to write a commit message. It is important
to write good commit messages, describing the reason for the change. The first
line should be a summary, and should start with restapi:. Then a blank line
and your description of the change. For example:
restapi: Improve the documentation of vm.start
This patch improves the documentation of the "vm.start"
operation, so that it is clear that the default value
of the "pause" parameter is "false".
Write the file, and you are ready to submit it:
$ git push origin HEAD:refs/for/master
If this finishes correctly it will give you the URL of the change. Go there and make sure that there is at least a reviewer for your change. In case of doubt add Juan Hernández as reviewer.
The reviewer may ask you to do changes to your patch, and will be happy to assist you with any doubts you have with the tools.
Eventually your patch will be merged and will be part of the reference documentation distributed with the next release of the software.
If your changes are simple enough there may be no need to test them, just submit the patch. But if you are making larger changes you may want to se how they will look like in the generated documentation. Currently this process is a bit involved, but it will be easier in the future.
The first step is that you need to build the tools that process the
documentation, and use them to generate the JSON representation of the
model. These tools are part of the ovirt-engine repository that you
have already cloned. To build it it is necessary to have Java and
Maven installed. Won't go into the details here, but there are
plenty of online resources that explain how to do it.
Once you have Java and Maven installed go to the ovirt-engine
directory and run the mvn clean install -DskipTests command:
$ cd ovirt-engine
$ mvn clean install -DskipTests
The first time you do this it will take a long time, and it will download
a good amount of stuff to your $HOME/.m2 directory. Be patient, next
times it won't take that long, because you can build only the component
that contains the model:
$ cd ovirt-engine
$ cd backend/manager/modules/restapi/interface/definition
$ mvn clean install -DskipTests
One of the results of this process will be a model.json file:
$ find . -name model.json
target/generated-resources/model.json
This file contains a description of the model, including the documentation. Take note of the location of this file, as it will be needed later.
The second step is to install the documentation viewer. This isn't
currently part of the ovirt-engine repository, so you need to
clone a different git repository, hosted in GitHub:
$ git clone https://github.com/jhernand/ovirt-api-explorer.git
This repository contains a JavaScript application. To use it it
needs to be hosted in a web server. If you already have a running
web server you can put the application there. Or you can also
use npm. For more details see
here.
Once this application is ready you can replace the model.json file
that it contains with the one that you built in the previous step,
reload the page and go to the relevant location. For example,
assuming that you are using npm:
$ cd ovirt-api-exporer
$ cp .../model.json app/model.json
$ npm start
Then go with your browser to the relevant location:
http://localhost:8000/app/#/services/vm/methods/start
If you have any question, issue, or feedback please contact Juan Hernández.