On Tue, Feb 9, 2016 at 4:26 PM, Matthew Jordan <mjor...@digium.com> wrote:
> > > On Tue, Feb 9, 2016 at 3:56 AM, Dan Jenkins <dan.jenkin...@gmail.com> > wrote: > >> Hi Everyone, >> >> I've been looking at how we can add proxy support (1) to the Node.js ARI >> Client for the past couple of days and have hit a few issues which I'm sure >> we'll be able to work out. But this has led me down the path of looking >> into the current status of swagger. >> >> Swagger recently donated it's specification to the OpenAPI initiative and >> so the specification is now called the OpenAPI specification. It was also >> bumped to version 2.0 (2). While updating a dependency for no real gain >> isn't always seen as a good thing. In this case, I feel we are going to get >> to a point (and are already nearing it) where tools that we want to use >> around swagger will become obsolete for the version of swagger we are using >> within Asterisk. >> >> I've been looking at generating libraries from the swagger specification >> and came across many many issues because we're using version 1.1 - the >> swagger team were surprised I was even attempting it. The other code >> generator I was looking at has a minimum of specification version 1.2. I >> fear this issue will only get worse as time goes on. >> > > I do think it would be good for us to upgrade our version of Swagger we're > using. We're really using a strange hybrid of 1.1 and 1.2 (mostly 1.1), due > to the state of flux the 1.2 specification was in when we added the ARI API > to Asterisk. > > That aside, I will note a few personal issues I have with Swagger: > (1) Their version bumps are all major. 1.1 to 1.2 is a massive change; 1.2 > to 2.0 is another massive change. They don't adhere to semantic versioning, > and you can expect pedantic changes that add little value but break > compatibility horribly to be in any version change. Since we wrote our own > Swagger generator to build the C code for ARI, this is a major project for > Asterisk. > (2) As a project, they are absolutely terrible at backwards compatibility; > their recent statement of deprecating swagger-tools [1] does not fill me > with confidence that they are going to get better at supporting the users > of their specification/libraries. We absolutely will be chasing a moving > target if we try to keep compatibility with them. > (3) This doesn't just impact Asterisk; any client library that works with > ARI has to accommodate multiple schema versions. For the ari-py library, > that's going to be inherently destructive, as it only understands the 1.1 > schema. It also means we can't update our Swagger support without breaking > existing applications. > > All of my griping aside, I do think it is good to update our Swagger > version when doing so makes the lives of Asterisk developers better, but I > think updating for the sake of staying in lock-step with Swagger is not > going to end well for the project. (It honestly feels like chasing Google > Talk/Voice and their never-ending changes to their "spec".) > > >> >> Now, I'm not saying we need to change it right now, and I know there are >> inherent difficulties with upgrading the version of the specification that >> we use, as it then ruins libraries that expect to work with swagger version >> 1.1 etc, however, I think we do need a plan to update the version - whether >> that's with Asterisk 14 or whatever; as long as its on the roadmap then I'm >> happy, currently I don't think it is. >> >> What are people's thoughts? >> >> > I think it would be good to put it on the list of things that would be > nice to see in Asterisk 14. > > I will say that this is one of the very few places in Asterisk where > someone without C experience could contribute! The generators are all > written in Python, using mustache templates to build out the wiki > documentation and C implementation/header files. So long as you don't > change the structure of what is fed to the mustache templates, you could > conceivably update the JSON and Python interpreters and not have to know a > single line of C code. > > [1] https://github.com/apigee-127/swagger-tools/issues/335 > > -- > Matthew Jordan > Digium, Inc. | Director of Technology > 445 Jan Davis Drive NW - Huntsville, AL 35806 - USA > Check us out at: http://digium.com & http://asterisk.org > > -- > _____________________________________________________________________ > -- Bandwidth and Colocation Provided by http://www.api-digital.com -- > > asterisk-dev mailing list > To UNSUBSCRIBE or update options visit: > http://lists.digium.com/mailman/listinfo/asterisk-dev > If that's the case, should we consider moving to another project? the JSON API spec is pretty nice (1). Or open a dialogue with the swagger team now that it's "Open API Spec" and see whether anything is going to change in terms of how they update things? I completely agree with you on the not so nice upgrade paths and breaking things within what I consider a minor version bump. If we're going to stick with swagger/openAPI even though we might not be fans of how they update the specification, then we can put some time into helping upgrade the ARI interface but I'd rather think about swapping out for another spec now rather than do the work and feel like we're still painted into a corner. Sorry, I know that's a rather radical move/statement but thought I'd put it out there. 1.http://jsonapi.org/
-- _____________________________________________________________________ -- Bandwidth and Colocation Provided by http://www.api-digital.com -- asterisk-dev mailing list To UNSUBSCRIBE or update options visit: http://lists.digium.com/mailman/listinfo/asterisk-dev
