openstack-manuals

Autogenerate API Reference

Registered by Tom Fifield

The API Reference at (http://api.openstack.org/api-ref.html) currently consists of xml and json samples copied from respective product repositories, and hand-crafted WADL. The samples will soon be automatically copied (https://blueprints.launchpad.net/openstack-manuals/+spec/api-samples-to-api-site), however significant time and effort is still spent on writing the WADL.

This blueprint aims to implement a system which will automatically generate the WADL definition of the various OpenStack APIs, to ensure completeness, correctness - and lowering the effort required in the process.

Blueprint information

Status:
Complete
Approver:
Anne Gentle
Priority:
High
Drafter:
Tom Fifield
Direction:
Needs approval
Assignee:
None
Definition:
Superseded
Series goal:
Accepted for liberty
Implementation:
Not started
Milestone target:
milestone icon liberty
Completed by
Lana

Related branches

Sprints

Whiteboard

We need to readdress this, in light of the move away from WADL. --LKB

We don't really want autogenerated API documentation, because then how do you know if the code is correct? How can a quality engineer or SDK dev trust the output? Autogeneration is fine for the first set of docs but after that need to be treated as the "contract" for SDK developers to trust.

Clarification of intent of blueprint @ http://lists.openstack.org/pipermail/openstack-docs/2015-April/006502.html

(?)

Work Items

Dependency tree

* Blueprints in grey have been implemented.

Nearby

This blueprint contains Public information 
Everyone can see this information.