Summary:	ASTERISK-24300: API docs don't conform to stated Swagger version
Reporter:	Bradley Watkins (marquis)	Labels:
Date Opened:	2014-09-05 14:43:32	Date Closed:
Priority:	Major	Regression?
Status:	Open/New	Components:	Documentation
Versions:	SVN 12.5.1 13.0.0-beta1	Frequency of Occurrence
Related Issues:	is duplicated by ASTERISK-24296 events.json has deprecated attributes
Environment:		Attachments:
Description:	For at least events.json, the stated Swagger version (in that case 1.2) is not what's actually in use.  It appears, based on some historical asterisk-dev mailing list posts, that an in-progress version of 1.2 was used.  However, now that 1.2 has been finalized I think it's important to update the models and code generation tools to that spec. As it stands, any tools built to work with the 1.2 standard will not function correctly against Asterisk's api docs.
Comments:	By: Bradley Watkins (marquis) 2014-09-21 11:50:47.286-0500 This issue has not been resolved. I believe you meant to resolve ASTERISK-24296 instead, as that's what was committed. By: Leif Madsen (lmadsen) 2014-10-07 13:16:34.716-0500 Reopened at the request of @marquis42 By: Leif Madsen (lmadsen) 2014-10-07 13:20:49.847-0500 [~mjordan], [~rnewton], I've reopened this at the request of Brad. By: Matt Jordan (mjordan) 2014-10-07 16:04:18.338-0500 Thanks - yeah, I tagged this to the wrong issue. Sorry about that. By: Matt Jordan (mjordan) 2014-10-14 16:53:48.760-0500 FYI, this is *not* a minor version bump. I'm not sure what lunatic versioning scheme the Swagger guys are following, but if anything is a case study on "what not to do" when doing a minor version bump, this is it: https://github.com/wordnik/swagger-spec/wiki/1.2-transition I'm scared to even look at the 1.2 => 2.0 transition. While I do think we will need to jump to 1.2, there's no way to get there from here without potentially breaking client libraries that rely on Swagger. I'm inclined to punt this to Asterisk 14, although I'd hate to do that and then have wordnik decide to totally stop supporting Swagger 1.1. By: Matthias Urlichs (smurfix) 2018-01-13 07:36:22.196-0600 OK, this bug is >three years old, swagger has been renamed to OpenAPI, is now at version 3, and the problem still hasn't been solved. IMHO Asterisk 16 should use an uptodate version of -Swagger-OpenAPI. Benefits include a reasonably-specified protocol (Swagger 1.1 is not) and the fact that there is a verifying async Python3 client library for OpenAI 3.0, while nobody in their right mind spends any time on implementing asyncio support for what exists for 1.1. Thoughts? By: Matthias Urlichs (smurfix) 2018-01-13 07:37:33.131-0600 NB, I should be able to help implementing and/or testing. By: Corey Farrell (coreyfarrell) 2018-01-13 11:54:22.553-0600 -You mentioned Python3, what about Python2?  I know everyone is trying to move on but RHEL/CentOS do not have Python3 (as part of the OS or even in EPEL).  I know CentOS packages get annoyingly old but I think at minimum the latest version of CentOS needs 1st class support.- -In addition the Asterisk testsuite does not yet run with Python3.  At this stage I think it would be OK for us to make backwards compatible changes to allow the testsuite to work under Python3, but running under Python2 is still a requirement (about half the test agents are CentOS 7).- Looks like I didn't search hard enough, EPEL7 has a 'python34' package so CentOS support is not an issue.  Last I knew the testsuite would not run under python3, so any work done here would need to ensure the testsuite can still function. By: Matthias Urlichs (smurfix) 2019-03-12 03:29:16.826-0500 Well, another year has gone by, Asterisk 16 is out and still uses Swagger 1.1, and the number of tools that can talk to Asterisk actually gets smaller as they're unmaintained (nobody else seems to use Swagger 1.x any more, AFAICT). IMHO, long-term we need an /ari2/ endpoint that uses OpenAPIv3 instead (and then deprecate /ari/). By: Jonathan Harris (lardconcepts) 2021-05-16 10:08:39.554-0500 Another two years have gone by, and the version of Swagger in use is now almost a decade old. The node libraries are unmaintained and throw up a bunch of warnings. I agree with Matthias that it would be very beneficial to have a v2 (v3?!) endpoint so we could use current libraries. Thank you.