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 <d...@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 <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 >
__________________________________________________________________________ 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