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