Open Stack

Hey doug,

Thanks your reply. Very good question.
It is not a conflict with current API Documents work that has already been
done.
We can use some tools to generate Open API schema from existing machine
readable API-def in every project like nova [1]
We can still use the existing tools to generate the API Documents website.

[1] https://github.com/openstack/nova/tree/master/api-ref/source

Best Regards,
Edison Xiang

On Fri, Aug 31, 2018 at 1:46 AM Doug Hellmann <doug at doughellmann.com> wrote:

> Excerpts from Edison Xiang's message of 2018-08-30 14:08:12 +0800:
> > Hey dims,
> >
> > Thanks your reply. Your suggestion is very important.
> >
> > > what would be the impact to projects?
> > > what steps they would have to take?
> >
> > We can launch a project to publish OpenStack Projects APIs Schema for
> users
> > and  developers.
> > But now OpenStack Projects have no APIs Schema definition.
> > Open API will not impact OpenStack Projects features they have,
> > but we need some volunteers to define every project APIs Schema by Open
> API
> > 3.0.
> >
> > > Do we have a sample/mock API where we can show that the Action and
> > Microversions can be declared to reflect reality and it can actually work
> > with the generated code?
> > Yeah, you can copy this yaml [1] into editor [2] to generate server or
> > client codes or try it out.
> > We can do more demos later.
> >
> > [1]
> >
> https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml
> > [2] https://editor.swagger.io
> >
> > Best Regards,
> > Edison Xiang
>
> How does this proposal relate to the work that has already been
> done to build the API guide
> https://developer.openstack.org/api-guide/quick-start/ documentation?
>
> Doug
>
> >
> > On Wed, Aug 29, 2018 at 6:31 PM Davanum Srinivas <davanum at gmail.com>
> wrote:
> >
> > > Edison,
> > >
> > > This is definitely a step in the right direction if we can pull it off.
> > >
> > > Given the previous experiences and the current situation of how and
> where
> > > we store the information currently and how we generate the website for
> the
> > > API(s), can you please outline
> > > - what would be the impact to projects?
> > > - what steps they would have to take?
> > >
> > > Also, the whole point of having these definitions is that the generated
> > > code works. Do we have a sample/mock API where we can show that the
> Action
> > > and Microversions can be declared to reflect reality and it can
> actually
> > > work with the generated code?
> > >
> > > Thanks,
> > > Dims
> > >
> > > On Wed, Aug 29, 2018 at 2:37 AM Edison Xiang <xiang.edison at gmail.com>
> > > wrote:
> > >
> > >> Hi team,
> > >>
> > >> As we know, Open API 3.0 was released on July, 2017, it is about one
> year
> > >> ago.
> > >> Open API 3.0 support some new features like anyof, oneof and allof
> than
> > >> Open API 2.0(Swagger 2.0).
> > >> Now OpenStack projects do not support Open API.
> > >> Also I found some old emails in the Mail List about supporting Open
> API
> > >> 2.0 in OpenStack.
> > >>
> > >> Some limitations are mentioned in the Mail List for OpenStack API:
> > >> 1. The POST */action APIs.
> > >>     These APIs are exist in lots of projects like nova, cinder.
> > >>     These APIs have the same URI but the responses will be different
> when
> > >> the request is different.
> > >> 2. Micro versions.
> > >>     These are controller via headers, which are sometimes used to
> > >> describe behavioral changes in an API, not just request/response
> schema
> > >> changes.
> > >>
> > >> About the first limitation, we can find the solution in the Open API
> 3.0.
> > >> The example [2] shows that we can define different request/response in
> > >> the same URI by anyof feature in Open API 3.0.
> > >>
> > >> About the micro versions problem, I think it is not a limitation
> related
> > >> a special API Standard.
> > >> We can list all micro versions API schema files in one directory like
> > >> nova/V2,
> > >> or we can list the schema changes between micro versions as tempest
> > >> project did [3].
> > >>
> > >> Based on Open API 3.0, it can bring lots of benefits for OpenStack
> > >> Community and does not impact the current features the  Community has.
> > >> For example, we can automatically generate API documents, different
> > >> language Clients(SDK) maybe for different micro versions,
> > >> and generate cloud tool adapters for OpenStack, like ansible module,
> > >> terraform providers and so on.
> > >> Also we can make an API UI to provide an online and visible API
> search,
> > >> API Calling for every OpenStack API.
> > >> 3rd party developers can also do some self-defined development.
> > >>
> > >> [1] https://github.com/OAI/OpenAPI-Specification
> > >> [2]
> > >>
> https://github.com/edisonxiang/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml#L94-L109
> > >> [3]
> > >>
> https://github.com/openstack/tempest/tree/master/tempest/lib/api_schema/response/compute
> > >>
> > >> Best Regards,
> > >> Edison Xiang
> > >>
> > >>
> __________________________________________________________________________
> > >> OpenStack Development Mailing List (not for usage questions)
> > >> Unsubscribe:
> > >> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> > >>
> > >
> > >
> > > --
> > > Davanum Srinivas :: https://twitter.com/dims
> > >
> __________________________________________________________________________
> > > OpenStack Development Mailing List (not for usage questions)
> > > Unsubscribe:
> OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> > >
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20180831/13403d27/attachment-0001.html>