Bug 1201197 - [RFE] Automatically generate the reference documentation of the RESTAPI
Summary: [RFE] Automatically generate the reference documentation of the RESTAPI
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: ovirt-engine
Classification: oVirt
Component: RestAPI
Version: ---
Hardware: Unspecified
OS: Unspecified
unspecified
medium vote
Target Milestone: ovirt-4.1.0-alpha
: 4.1.0
Assignee: Juan Hernández
QA Contact: Lucie Leistnerova
URL:
Whiteboard:
Depends On:
Blocks: 1061384 1148393
TreeView+ depends on / blocked
 
Reported: 2015-03-12 09:55 UTC by Juan Hernández
Modified: 2017-02-01 14:59 UTC (History)
11 users (show)

Fixed In Version:
Doc Type: Enhancement
Doc Text:
Clone Of:
Environment:
Last Closed: 2017-02-01 14:59:32 UTC
oVirt Team: Infra
juan.hernandez: ovirt-4.1?
lsvaty: testing_plan_complete+
ylavi: planning_ack?
rule-engine: devel_ack+
lsvaty: testing_ack+


Attachments (Terms of Use)


Links
System ID Private Priority Status Summary Last Updated
oVirt gerrit 45852 0 None None None Never

Description Juan Hernández 2015-03-12 09:55:17 UTC
Currently the reference documentation of the RESTAPI is written manually. As a result it requires a lot of effort and gets out of sync very quickly.

To be able to have an updated reference documentation it is convenient to generate it automatically from the metadata provided by the engine, currently the XML schema of the entities and the RSDL document that describes the capabilities of the resources.

There are two main tasks that we will need to do:

1. We will need to create a mechanism to associate pieces of documentation with the descriptions of the entities and resources. These could be documentation annotations in the XML schema, documentation elements in the RSDL metadata file, documentation comments in the Java interfaces of the resources, or any other mechanism that we consider appropriate. We will also need to create a tool to extract those pieces of documentation and to generate the actual documents. These could be similar to the tools that we use to generate the Python and Java SDKs.

2. We will need to actually write the pieces of documentation.

The first task is technically complicated, but feasible. It will require an amount of effort similar to the initial creation of the Python or Java SDKs.

The second task isn't technically complicated, but it requires a lot of work, probably by multiple people, as no one knows completely all capabilities of the RESTAPI.

Comment 1 Red Hat Bugzilla Rules Engine 2015-10-19 11:00:19 UTC
Target release should be placed once a package build is known to fix a issue. Since this bug is not modified, the target version has been reset. Please use target milestone to plan a fix for a oVirt release.

Comment 2 Juan Hernández 2015-11-25 12:18:43 UTC
The first steps towards addressing this issue have already been taken. The API has now a specification language (the metamodel) and it will soon have a way to deliver it to users, in its source form and also in XML and JSON:

  https://gerrit.ovirt.org/#/q/status:open+project:ovirt-engine+branch:master+topic:metamodel_server

My suggestion for generating the documentation is to create a web application that users can use to explore the documentation of the API. I have created a prototype of that web application here:

  https://github.com/jhernand/ovirt-api-explorer

This application is intended to be eventually included in the server, and also to be used standalone, as purely static content. An example is available here:

  https://jhernand.fedorapeople.org/ovirt-api-explorer

Comment 3 Juan Hernández 2016-04-06 11:15:42 UTC
There haven't been any advances in adding the documentation to the model repository described in comment 2. So even if the mechanism is ready, there won't probably be any useful content ready for version 4.0 of the engine. So I'm re-targeting to 4.1.

Comment 4 Sandro Bonazzola 2016-12-12 14:03:44 UTC
The fix for this issue should be included in oVirt 4.1.0 beta 1 released on December 1st. If not included please move back to modified.

Comment 5 Lucie Leistnerova 2017-01-02 13:36:59 UTC
Link on welcome page is functional. I tried to click randomly around the document links and in left menu tree. All was OK. By resizing browsers window page refreshes OK.

verified in ovirt-engine-4.1.0-0.3.beta2.el7.noarch

tested in Firefox 50.1.0 and Google Chrome 55.0

Comment 6 Lucie Leistnerova 2017-01-10 15:03:07 UTC
relevant test case: RHEVM3-8689


Note You need to log in before you can comment on or make changes to this bug.