Re: [openstack-dev] [docs] [api] Swagger limitations?

[Chris Dent]

On Tue, 17 May 2016, Jamie Hannaford wrote:


Completely agree. The good news is that the API-WG have a spec in
review (https://review.openstack.org/#/c/234994/) which might solve
these problems. They want to make actions first-class resources in the
API. From my initial understanding, this could be represented in
Swagger without the need for vendor extensions.


For clarity, you might note a few things about that review:

* Last real work on it was back in January
* There are 4 -1 votes and only one +1 (which is from October)

Suffice it to say that that proposal (and the entire concept of how
to represent actions in a RESTful API) was contentious enough that we
stalled out. The main people who were in favor of trying to get some
kind of pro-actions guideline in place have had to step back from
participation in the  API-wg[1]. Until we are able to have a new
conversation about the issues, with a diverse set of participants,
it's not likely to see much progress.

[1] This is an all too common happening in cross-project work.

--
Chris Dent   (╯°□°)╯︵┻━┻http://anticdent.org/
freenode: cdent tw: @anticdent__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs] [api] Swagger limitations?

[Anne Gentle]

On Tue, May 17, 2016 at 9:51 AM, Jamie Hannaford <
jamie.hannaf...@rackspace.com> wrote:

> Hi Anne,
>
>
> So it seems that the only remaining issues are:
>
>
> - using $ref, which is not supported by some upstream tools
>
> - embedding Heat templates in a Swagger doc (not applicable to most
> OpenStack services)
>
>
> I responded to the other two in my e-mail to Sean. For the $ref problem,
> what is the problem with using NPM packages like swagger-tools or
> swagger-parser [1][2]? They can deference Swagger files into one unified
> file, which the build tool can then use for HTML rendering. The alternative
> is to let each project choose whether to use $ref or not. If they do want
> to spread Swagger docs out into separate documents and reference them, they
> will need to use a tool in whatever language that works.
>
>
>
It's not that these mechanisms are not supported. It's that we don't have
assigned development resources to work on Swagger/OpenAPI solutions.

In my first reply I sent you a link to an example using OpenStack
infrastructure already in place to use npm tooling to build. Please feel
free to test with that example: https://review.openstack.org/#/c/286659/

Anne


> I agree that Swagger is a new tool in a new ecosystem, but it definitely
> solves a lot of our use cases. I think it'd be a lot stronger if we adopted
> it - at least partially - and contributed our ideas for improvement back
> upstream.
>
>
> Was there any cons/disadvantages that I missed which would prevent is
> incorporating it?
>
>
> Jamie
>
>
> [1] https://www.npmjs.com/package/swagger-parser
>
> [2] https://github.com/jamiehannaford/swagger-magnum/blob/master/deref.js
>
>
> --
> *From:* Anne Gentle 
> *Sent:* 17 May 2016 15:35
> *To:* OpenStack Development Mailing List (not for usage questions)
> *Subject:* Re: [openstack-dev] [docs] [api] Swagger limitations?
>
>
>
> On Tue, May 17, 2016 at 7:57 AM, Jamie Hannaford <
> jamie.hannaf...@rackspace.com> wrote:
>
>> Hi all,
>>
>>
>> Back in March Anne wrote a great summary on the current state of Swagger
>> for OpenStack docs:
>> http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.
>> <http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html>
>>  Is this still the current state of things? Magnum is looking to
>> document its API soon, so I want to look at the feasibility of doing it in
>> Swagger. If it's not possible, RST should suffice.
>>
>>
>>
> Hi Jamie, thanks for asking. There are a few more limitations/concerns
> that I'll outline below.
>
>
>> In terms of the specific limitations that were listed:
>>
>>
>> - the /actions endpoint. Would it be possible to use vendor extensions to
>> solve this problem? For example, imagine that you want to document reboot
>> and rebuild operations. You could create custom verb properties for these
>> operations (`x-post-reboot`, `x-post-rebuild`) that would allow
>> differentiation of the JSON payload under the same URL category. The HTML
>> rendering would need to be adapted to take this into consideration. [1]
>>
>>
>> Yes, our first goal is to migrate off of WADL, but that won't prevent use
> of Swagger, it just means the first priority is to get all projects off of
> WADL.
>
> I think the details and nuances here were fairly well communicated in the
> rest of the thread [1] and in the etherpads, but of course that requires a
> LOT of reading. :)
>
> The main points I'd also like to ensure you know we discussed are [2]:
> 
> The current Plan of Record is to move to swagger. However this doesn't
> address a number of key issues:
> - swagger is young, most community tools around swagger are 50% - 80%
> solutions
> - swagger provides no facility for nova's 'action' interfaces or
> microversions
>
> NOTE: actions are used by nova, cinder, manilla, trove, neutron (in
> extensions) - so 40% of the 12 APIs documented on
> http://developer.openstack.org/ but only 5 of 19 (26%) REST APIs in
> OpenStack's governance
>
> NOTE: microversions are used by nova, manilla, ironic, and cinder (and
> neutron probably in the future unless it proves awful to document and use)
>
> NOTE: while Heat neither uses actions or microversions, it's content
> templates as inline post requests makes the swagger definition potentially
> really tough. Not that there shouldn't be full docs for those formats, but
> they just don't do that today. This same issue will hit other APIs that
> support post req

Re: [openstack-dev] [docs] [api] Swagger limitations?

[Jamie Hannaford]

Hi Anne,


So it seems that the only remaining issues are:


- using $ref, which is not supported by some upstream tools

- embedding Heat templates in a Swagger doc (not applicable to most OpenStack 
services)


I responded to the other two in my e-mail to Sean. For the $ref problem, what 
is the problem with using NPM packages like swagger-tools or swagger-parser 
[1][2]? They can deference Swagger files into one unified file, which the build 
tool can then use for HTML rendering. The alternative is to let each project 
choose whether to use $ref or not. If they do want to spread Swagger docs out 
into separate documents and reference them, they will need to use a tool in 
whatever language that works.


I agree that Swagger is a new tool in a new ecosystem, but it definitely solves 
a lot of our use cases. I think it'd be a lot stronger if we adopted it - at 
least partially - and contributed our ideas for improvement back upstream.


Was there any cons/disadvantages that I missed which would prevent is 
incorporating it?


Jamie


[1] https://www.npmjs.com/package/swagger-parser

[2] https://github.com/jamiehannaford/swagger-magnum/blob/master/deref.js



From: Anne Gentle 
Sent: 17 May 2016 15:35
To: OpenStack Development Mailing List (not for usage questions)
Subject: Re: [openstack-dev] [docs] [api] Swagger limitations?



On Tue, May 17, 2016 at 7:57 AM, Jamie Hannaford 
mailto:jamie.hannaf...@rackspace.com>> wrote:

Hi all,


Back in March Anne wrote a great summary on the current state of Swagger for 
OpenStack docs: 
http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.<http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html>
  Is this still the current state of things? Magnum is looking to document its 
API soon, so I want to look at the feasibility of doing it in Swagger. If it's 
not possible, RST should suffice.


Hi Jamie, thanks for asking. There are a few more limitations/concerns that 
I'll outline below.


In terms of the specific limitations that were listed:


- the /actions endpoint. Would it be possible to use vendor extensions to solve 
this problem? For example, imagine that you want to document reboot and rebuild 
operations. You could create custom verb properties for these operations 
(`x-post-reboot`, `x-post-rebuild`) that would allow differentiation of the 
JSON payload under the same URL category. The HTML rendering would need to be 
adapted to take this into consideration. [1]


Yes, our first goal is to migrate off of WADL, but that won't prevent use of 
Swagger, it just means the first priority is to get all projects off of WADL.

I think the details and nuances here were fairly well communicated in the rest 
of the thread [1] and in the etherpads, but of course that requires a LOT of 
reading. :)

The main points I'd also like to ensure you know we discussed are [2]:

The current Plan of Record is to move to swagger. However this doesn't address 
a number of key issues:
- swagger is young, most community tools around swagger are 50% - 80% solutions
- swagger provides no facility for nova's 'action' interfaces or microversions

NOTE: actions are used by nova, cinder, manilla, trove, neutron (in extensions) 
- so 40% of the 12 APIs documented on http://developer.openstack.org/ but only 
5 of 19 (26%) REST APIs in OpenStack's governance

NOTE: microversions are used by nova, manilla, ironic, and cinder (and neutron 
probably in the future unless it proves awful to document and use)

NOTE: while Heat neither uses actions or microversions, it's content templates 
as inline post requests makes the swagger definition potentially really tough. 
Not that there shouldn't be full docs for those formats, but they just don't do 
that today. This same issue will hit other APIs that support post requests of 
3rd party content format. Tacker being a good instance.

- the swagger-tools npm package supports $ref, which will clearly be required 
for maintaining our APIs (autoconverted Nova API is 21KLOC, and probably would 
be triple that once missing parts are filled in).

NOTE: this is a brand new toolchain that is yet another speed bump in getting 
people to contribute and maintain, though it is maintained outside of OpenStack
---

Please do consider the additional concerns about $ref and tooling listed above.

In all the communication, I have not prevented the use of Swagger/OpenAPI but I 
want to make it clear that focused efforts are best for the earliest projects.

- microversions. The more I think about it, the more I realise that this is not 
really a Swagger limitation but more of a consideration that *any* 
documentation format needs to solve. It seems that per microversion release, a 
separate doc artefact is required which encapsulates the API at that point in 
time. This would be very easy to do in Swagger compared to RST 

Re: [openstack-dev] [docs] [api] Swagger limitations?

[Anne Gentle]

On Tue, May 17, 2016 at 9:13 AM, Jamie Hannaford <
jamie.hannaf...@rackspace.com> wrote:

> All great points, thanks Anne and Sean. My responses are inline.
>
> 
> From: Sean Dague 
> Sent: 17 May 2016 15:30
> To: openstack-dev@lists.openstack.org
> Subject: Re: [openstack-dev] [docs] [api] Swagger limitations?
>
> On 05/17/2016 08:57 AM, Jamie Hannaford wrote:
> > Hi all,
> >
> >
> > Back in March Anne wrote a great summary on the current state of Swagger
> > for OpenStack
> > docs:
> http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.
> > <
> http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html>
> >  Is this still the current state of things? Magnum is looking to
> > document its API soon, so I want to look at the feasibility of doing it
> > in Swagger. If it's not possible, RST should suffice.
> >
> >
> > In terms of the specific limitations that were listed:
> >
> >
> > - the /actions endpoint. Would it be possible to use vendor extensions
> > to solve this problem? For example, imagine that you want to document
> > reboot and rebuild operations. You could create custom verb properties
> > for these operations (`x-post-reboot`, `x-post-rebuild`) that would
> > allow differentiation of the JSON payload under the same URL category.
> > The HTML rendering would need to be adapted to take this into
> > consideration. [1]
>
> If you do this you're now outside the swagger spec, which means that all
> the toolchains in swagger that exist to:
>
> * build docs
> * build clients
> * build tests
>
> No longer apply to your API.
>
> So yes, you could do this, but in doing so you abandon most of the
> ecosystem that makes swagger interesting, and now have to maintain all
> your own dedicated tooling.
>
> There is no swagger HTML rendering project in OpenStack that can be
> simply modified for this. One of the advantages for swagger was that
> would be an upstream ecosystem tool to build things like the API site.
> You now give that up and take on a multi person year engineering effort
> to build a custom documentation site rendering engine (probably in
> javascript, as that's where most of the starting components are).
> Swagger is also pretty non trivial in the way references are resolved,
> so this may end up a *really* big engineering effort.
>
> I agree, but I don't think it's an unreasonable compromise to make
> because, at least in the context of OpenStack's ecosystem, we already
> provide much of that tooling to end-users. We have a plethora of clients
> already out there and a project underway to unify them into a single
> client. So I don't think we'd be putting users at a disadvantage by using
> our own vendor extensions, so long as they're well designed and well
> documented.
>
> The only inconvenience would be to adapt the build process to take custom
> verbs into consideration. In my opinion that's more of a short-term
> software challenge for contributors rather than an insurmountable one that
> affects end-users. Then again, I don't have much experience with the
> build/infra process, so please call me out if that's a complete
> mischaracterisation :)
>
> While I accept that it's definitely preferable to use upstream tools when
> they're useful, with such a complex beast like OpenStack, how long do you
> think we could carry on using vanilla upstream tools? At some point we
> would probably need to roll out our own modifications to satisfy our use
> cases. In terms of it requiring a multi-person engineering effort, isn't
> that already the remit of the current docs team?
>

In a word, No. We have not had dedicated development resources specifically
for API docs since 2013.

Do you have ideas for how to bring this type of development resource into
the OpenStack community? I've tried. I have worked on this for
fairy-slipper, with the API working group, and with the docs tools team,
and it leaves me with the sense that we must prioritize due to lack of
development resources.


> > - microversions. The more I think about it, the more I realise that this
> > is not really a Swagger limitation but more of a consideration that
> > *any* documentation format needs to solve. It seems that per
> > microversion release, a separate doc artefact is required which
> > encapsulates the API at that point in time. This would be very easy to
> > do in Swagger compared to RST (single file vs directory of RST files).
>
> You could go that route, and depending on how often you change your
> format, and how

Re: [openstack-dev] [docs] [api] Swagger limitations?

[Jamie Hannaford]

All great points, thanks Anne and Sean. My responses are inline.


From: Sean Dague 
Sent: 17 May 2016 15:30
To: openstack-dev@lists.openstack.org
Subject: Re: [openstack-dev] [docs] [api] Swagger limitations?

On 05/17/2016 08:57 AM, Jamie Hannaford wrote:
> Hi all,
>
>
> Back in March Anne wrote a great summary on the current state of Swagger
> for OpenStack
> docs: 
> http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.
> <http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html>
>  Is this still the current state of things? Magnum is looking to
> document its API soon, so I want to look at the feasibility of doing it
> in Swagger. If it's not possible, RST should suffice.
>
>
> In terms of the specific limitations that were listed:
>
>
> - the /actions endpoint. Would it be possible to use vendor extensions
> to solve this problem? For example, imagine that you want to document
> reboot and rebuild operations. You could create custom verb properties
> for these operations (`x-post-reboot`, `x-post-rebuild`) that would
> allow differentiation of the JSON payload under the same URL category.
> The HTML rendering would need to be adapted to take this into
> consideration. [1]

If you do this you're now outside the swagger spec, which means that all
the toolchains in swagger that exist to:

* build docs
* build clients
* build tests

No longer apply to your API.

So yes, you could do this, but in doing so you abandon most of the
ecosystem that makes swagger interesting, and now have to maintain all
your own dedicated tooling.

There is no swagger HTML rendering project in OpenStack that can be
simply modified for this. One of the advantages for swagger was that
would be an upstream ecosystem tool to build things like the API site.
You now give that up and take on a multi person year engineering effort
to build a custom documentation site rendering engine (probably in
javascript, as that's where most of the starting components are).
Swagger is also pretty non trivial in the way references are resolved,
so this may end up a *really* big engineering effort.

I agree, but I don't think it's an unreasonable compromise to make because, at 
least in the context of OpenStack's ecosystem, we already provide much of that 
tooling to end-users. We have a plethora of clients already out there and a 
project underway to unify them into a single client. So I don't think we'd be 
putting users at a disadvantage by using our own vendor extensions, so long as 
they're well designed and well documented.

The only inconvenience would be to adapt the build process to take custom verbs 
into consideration. In my opinion that's more of a short-term software 
challenge for contributors rather than an insurmountable one that affects 
end-users. Then again, I don't have much experience with the build/infra 
process, so please call me out if that's a complete mischaracterisation :)

While I accept that it's definitely preferable to use upstream tools when 
they're useful, with such a complex beast like OpenStack, how long do you think 
we could carry on using vanilla upstream tools? At some point we would probably 
need to roll out our own modifications to satisfy our use cases. In terms of it 
requiring a multi-person engineering effort, isn't that already the remit of 
the current docs team?

> - microversions. The more I think about it, the more I realise that this
> is not really a Swagger limitation but more of a consideration that
> *any* documentation format needs to solve. It seems that per
> microversion release, a separate doc artefact is required which
> encapsulates the API at that point in time. This would be very easy to
> do in Swagger compared to RST (single file vs directory of RST files).

You could go that route, and depending on how often you change your
format, and how big your API is, it may or may not be cumbersome. Fixes
to a base resource would require fixing it in N copies of the file.

If my understanding is correct, this would not happen. Each microversion, when 
released, is locked and would be preserved in that doc artefact. If a new 
software release is needed to fix a bug, that change would be encapsulated in a 
microversion with its own doc file.

It would mean that users of your API must preselect the API version
first before seeing anything. And they will only see a pristine document
at that version.

They will not have access to change notes inline (i.e. "New in 2.12").
When looking at consuming an API. IMHO, that is something which is
incredibly useful in reading an API. It's existence in the python
standard lib makes it much clearer about whether you want to take
advantage of feature X, or decide you'd rather have compatibilit

Re: [openstack-dev] [docs] [api] Swagger limitations?

[Anne Gentle]

On Tue, May 17, 2016 at 7:57 AM, Jamie Hannaford <
jamie.hannaf...@rackspace.com> wrote:

> Hi all,
>
>
> Back in March Anne wrote a great summary on the current state of Swagger
> for OpenStack docs:
> http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.
> 
>  Is this still the current state of things? Magnum is looking to document
> its API soon, so I want to look at the feasibility of doing it in Swagger.
> If it's not possible, RST should suffice.
>
>
>
Hi Jamie, thanks for asking. There are a few more limitations/concerns that
I'll outline below.


> In terms of the specific limitations that were listed:
>
>
> - the /actions endpoint. Would it be possible to use vendor extensions to
> solve this problem? For example, imagine that you want to document reboot
> and rebuild operations. You could create custom verb properties for these
> operations (`x-post-reboot`, `x-post-rebuild`) that would allow
> differentiation of the JSON payload under the same URL category. The HTML
> rendering would need to be adapted to take this into consideration. [1]
>
>
> Yes, our first goal is to migrate off of WADL, but that won't prevent use
of Swagger, it just means the first priority is to get all projects off of
WADL.

I think the details and nuances here were fairly well communicated in the
rest of the thread [1] and in the etherpads, but of course that requires a
LOT of reading. :)

The main points I'd also like to ensure you know we discussed are [2]:

The current Plan of Record is to move to swagger. However this doesn't
address a number of key issues:
- swagger is young, most community tools around swagger are 50% - 80%
solutions
- swagger provides no facility for nova's 'action' interfaces or
microversions

NOTE: actions are used by nova, cinder, manilla, trove, neutron (in
extensions) - so 40% of the 12 APIs documented on
http://developer.openstack.org/ but only 5 of 19 (26%) REST APIs in
OpenStack's governance

NOTE: microversions are used by nova, manilla, ironic, and cinder (and
neutron probably in the future unless it proves awful to document and use)

NOTE: while Heat neither uses actions or microversions, it's content
templates as inline post requests makes the swagger definition potentially
really tough. Not that there shouldn't be full docs for those formats, but
they just don't do that today. This same issue will hit other APIs that
support post requests of 3rd party content format. Tacker being a good
instance.

- the swagger-tools npm package supports $ref, which will clearly be
required for maintaining our APIs (autoconverted Nova API is 21KLOC, and
probably would be triple that once missing parts are filled in).

NOTE: this is a brand new toolchain that is yet another speed bump in
getting people to contribute and maintain, though it is maintained outside
of OpenStack
---

Please do consider the additional concerns about $ref and tooling listed
above.

In all the communication, I have not prevented the use of Swagger/OpenAPI
but I want to make it clear that focused efforts are best for the earliest
projects.

> - microversions. The more I think about it, the more I realise that this
> is not really a Swagger limitation but more of a consideration that *any*
> documentation format needs to solve. It seems that per microversion
> release, a separate doc artefact is required which encapsulates the API at
> that point in time. This would be very easy to do in Swagger compared to
> RST (single file vs directory of RST files).
>
>
> Agreed. But are we going to solve the microversions display problem once
or twice? Right now, I'm focusing on RST + YAML, and microversions need to
be solved.

Plus I'd like your thoughts on maintenance of the $ref mechanism and HTML
publishing toolchain. We have a patch that lets us build to HTML using
npm-provided tooling [3], but I really need to focus on getting a
navigation for all OpenStack APIs to be read in a unified way on
developer.openstack.org so I haven't tried to make a nice header/footer on
that output.

Heh, I see Sean replying also, so I'll go ahead and send. Thanks Jamie.

Anne

1. http://lists.openstack.org/pipermail/openstack-dev/2016-March/090704.html
2. https://etherpad.openstack.org/p/api-site-in-rst
3. https://review.openstack.org/#/c/286659/

> Am I way off here? I would really like to hear others' opinions on
> this. Thanks for all the great work!
>
>
> Jamie
>
>
> [1]
> https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/EXTENSIONS.md
> ​
>
> --
> Rackspace International GmbH a company registered in the Canton of Zurich,
> Switzerland (company identification number CH-020.4.047.077-1) whose
> registered office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland.
> Rackspace International GmbH privacy policy can be viewed at
> www.rackspace.co.uk/legal/swiss-privacy-policy - This e-mail message may
> conta

Re: [openstack-dev] [docs] [api] Swagger limitations?

[Sean Dague]

On 05/17/2016 08:57 AM, Jamie Hannaford wrote:
> Hi all,
> 
> 
> Back in March Anne wrote a great summary on the current state of Swagger
> for OpenStack
> docs: 
> http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.
> 
>  Is this still the current state of things? Magnum is looking to
> document its API soon, so I want to look at the feasibility of doing it
> in Swagger. If it's not possible, RST should suffice.
> 
> 
> In terms of the specific limitations that were listed:
> 
> 
> - the /actions endpoint. Would it be possible to use vendor extensions
> to solve this problem? For example, imagine that you want to document
> reboot and rebuild operations. You could create custom verb properties
> for these operations (`x-post-reboot`, `x-post-rebuild`) that would
> allow differentiation of the JSON payload under the same URL category.
> The HTML rendering would need to be adapted to take this into
> consideration. [1]

If you do this you're now outside the swagger spec, which means that all
the toolchains in swagger that exist to:

* build docs
* build clients
* build tests

No longer apply to your API.

So yes, you could do this, but in doing so you abandon most of the
ecosystem that makes swagger interesting, and now have to maintain all
your own dedicated tooling.

There is no swagger HTML rendering project in OpenStack that can be
simply modified for this. One of the advantages for swagger was that
would be an upstream ecosystem tool to build things like the API site.
You now give that up and take on a multi person year engineering effort
to build a custom documentation site rendering engine (probably in
javascript, as that's where most of the starting components are).
Swagger is also pretty non trivial in the way references are resolved,
so this may end up a *really* big engineering effort.

> - microversions. The more I think about it, the more I realise that this
> is not really a Swagger limitation but more of a consideration that
> *any* documentation format needs to solve. It seems that per
> microversion release, a separate doc artefact is required which
> encapsulates the API at that point in time. This would be very easy to
> do in Swagger compared to RST (single file vs directory of RST files). 

You could go that route, and depending on how often you change your
format, and how big your API is, it may or may not be cumbersome. Fixes
to a base resource would require fixing it in N copies of the file.

It would mean that users of your API must preselect the API version
first before seeing anything. And they will only see a pristine document
at that version.

They will not have access to change notes inline (i.e. "New in 2.12").
When looking at consuming an API. IMHO, that is something which is
incredibly useful in reading an API. It's existence in the python
standard lib makes it much clearer about whether you want to take
advantage of feature X, or decide you'd rather have compatibility, and not.

As with everything, it's trade offs, and what you want to get out of it.

Swagger is a really interesting API Design Language. And if you start
with Swagger when designing your API you impose a set of constraints
that give you a bunch of benefits. If you go beyond it's constraints,
you have imposed a very large and novel DSL on your environment (which
is strictly no longer swagger), which means you get all the costs of
conforming to an external standard without any of the benefits.

I think that our actions interface turned out to be a mistake, but it's
one made so long ago that it's pretty embedded. Long term getting
ourselves out of that hole would be good.

The microversions model is something that I think would be worth
engaging the OpenAPI upstream community. Our current implementation is
pretty OpenStack specific, but the concept would apply to any open
source project with a REST API that is CDed at different rates by
different deployers.

-Sean

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [docs] [api] Swagger limitations?

[Jamie Hannaford]

Hi all,


Back in March Anne wrote a great summary on the current state of Swagger for 
OpenStack docs: 
http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.
  Is this still the current state of things? Magnum is looking to document its 
API soon, so I want to look at the feasibility of doing it in Swagger. If it's 
not possible, RST should suffice.


In terms of the specific limitations that were listed:


- the /actions endpoint. Would it be possible to use vendor extensions to solve 
this problem? For example, imagine that you want to document reboot and rebuild 
operations. You could create custom verb properties for these operations 
(`x-post-reboot`, `x-post-rebuild`) that would allow differentiation of the 
JSON payload under the same URL category. The HTML rendering would need to be 
adapted to take this into consideration. [1]


- microversions. The more I think about it, the more I realise that this is not 
really a Swagger limitation but more of a consideration that *any* 
documentation format needs to solve. It seems that per microversion release, a 
separate doc artefact is required which encapsulates the API at that point in 
time. This would be very easy to do in Swagger compared to RST (single file vs 
directory of RST files).


Am I way off here? I would really like to hear others' opinions on this. Thanks 
for all the great work!


Jamie


[1] 
https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/EXTENSIONS.md?



Rackspace International GmbH a company registered in the Canton of Zurich, 
Switzerland (company identification number CH-020.4.047.077-1) whose registered 
office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland. Rackspace 
International GmbH privacy policy can be viewed at 
www.rackspace.co.uk/legal/swiss-privacy-policy - This e-mail message may 
contain confidential or privileged information intended for the recipient. Any 
dissemination, distribution or copying of the enclosed material is prohibited. 
If you receive this transmission in error, please notify us immediately by 
e-mail at ab...@rackspace.com and delete the original message. Your cooperation 
is appreciated.
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev