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 <dava...@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.edi...@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-requ...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
