[asterisk-dev] Plan for updating the ARI Swagger Version

[Matthew Jordan]

On Tue, Feb 9, 2016 at 3:56 AM, Dan Jenkins <dan.jenkins88 at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20160209/9497e322/attachment.html>