----- Original Message ----- > > > ----- Original Message ----- > > > > I like this idea. I'd also propose that the format of the specification be > > something machine-readable, such as API-Blueprint (a simple subset of > > markdown, apiblueprint.org , also what apiary uses, if you've ever seen > > that) or RAML (a more structured YAML-based syntax, raml.org ). > > API-Blueprint is closer to what the keystone document uses. > > > > Making the documentation machine-readable means that it's much easier to > > verify that, in practice, the implementation of an API matches its > > specification and documentation, which is a problem that plagues many > > OpenStack projects right now. > > > > At the meeting today we discussed putting together an initial seed based > around the proposed API and based mostly on the identity-api work. Are > folks ok with api-blueprint [1] > > [1] http://apiblueprint.org
Vs. the more standard and canonical wadl path (that the rest of the components use to go into docbook)? It's probably worth pointing out that API spec vs API doc probably wants to be as close to 1:1 as possible - if the upstream tooling is wadl based I'd hate to spend too much time fighting it. _______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
