Open Stack

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
> >