Open Stack

On Sun, Apr 26, 2015 at 7:32 PM, Tom Fifield <tom at openstack.org> wrote:

> On 27/04/15 08:29, Anne Gentle wrote:
> >
> >
> > On Sun, Apr 26, 2015 at 7:24 PM, Tom Fifield <tom at openstack.org
> > <mailto:tom at openstack.org>> wrote:
> >
> >     Hi,
> >
> >     This isn't my patch, but I'm just pulling this on to the mailing list
> >     since I saw it languishing: https://review.openstack.org/#/c/155329/
> :)
> >
> >     In this patch, the sample json files are updated for new things that
> are
> >     coming in Kilo. However, as Anne notes: "This site is updated
> >     continually, but it seems like these JSON examples won't be accurate
> >     until the next version comes out. What should we do in this case?"
> >
> >     Then it's noted that we have folks using trunk, etc.
> >
> >     So - API site versioning - how do we solve it for "all APIs and those
> >     with extensions" ?
> >
> >
> > This needs blueprint-level design decisions and a spec. Ideally we'll
> > rid ourselves of WADL in the design as well.
> >
> > I'd like to take this on next release and I'm looking for collaborators.
> > Extensible APIs make versioning especially difficult.
>
> Of course - this is just an attempt to start the brainstorming, not fix
> the specific patch :)
>
>
>
Absolutely!

Ideas I'd like to poke at:
Migrate WADL content to Swagger, please look at WADL2Swagger
github.com/rackerlabs/wadl2swagger
Migrate WADL content to RAML
Move all API content into project repos, aggregate those into an API
reference site

If anyone is interested, let's talk at the Summit at the API docs session
whenever that lands.
Anne


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150426/2868deb1/attachment.html>