Note: This bug is displayed in read-only format because the product is no longer active in Red Hat Bugzilla.

Bug 1201197

Summary:	[RFE] Automatically generate the reference documentation of the RESTAPI
Product:	[oVirt] ovirt-engine	Reporter:	Juan Hernández <juan.hernandez>
Component:	RestAPI	Assignee:	Juan Hernández <juan.hernandez>
Status:	CLOSED CURRENTRELEASE	QA Contact:	Lucie Leistnerova <lleistne>
Severity:	medium	Docs Contact:
Priority:	unspecified
Version:	---	CC:	aburden, bazulay, bugs, gklein, lsurette, lsvaty, oourfali, rbalakri, sfroemer, srevivo, ykaul
Target Milestone:	ovirt-4.1.0-alpha	Keywords:	FutureFeature
Target Release:	4.1.0	Flags:	juan.hernandez: ovirt-4.1? lsvaty: testing_plan_complete+ ylavi: planning_ack? rule-engine: devel_ack+ lsvaty: testing_ack+
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	Enhancement
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2017-02-01 14:59:32 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	Infra	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:
Bug Depends On:
Bug Blocks:	1061384, 1148393

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