With Swagger you can either: 1: integrate the spec into the API source code or 2: have one single standalone JSON file that contains the whole specification (api-docs.json in this case)
I’m not a fan of integrating the Swagger specification into the code - seems to make for a VERY large amount of work, a huge amount of complexity and massive potential for introduction of bugs. I’ve taken the approach of a single static JSON file - MUCH more simple. All Mailman would need is to include this file (api-docs.json) as a static file that can be read or if there is no static file server in Mailman (is there? I haven’t looked) maybe create an api-docs.json endpoint in the API that returns the static file. Any tools that want to use the api-docs.json spec file don’t need to be included in Mailman core. The api-docs.json spec file would need to be kept up to date when the Mailman API changes but it’s really straightforward - building it in the first place is just tedious research on the methods and properties but maintaining it should be a matter of a few minutes work to update it when the API changes. I’ll need to finish it up. I’m not sure what to do about getting a pair of eyes to QA verify it, but maybe we can cross that bridge after I’ve finished it. On 12 Jan 2015, at 12:19 pm, Barry Warsaw <ba...@list.org> wrote: On Jan 11, 2015, at 08:51 AM, Andrew Stuart wrote: > Attached is a first pass at a Swagger spec for the REST API. > > You can find out about Swagger at http://swagger.io > > The Swagger spec that I am working on is attached to this message or can be > found here: http://www.mailripper.com/api-docs.json > > If you want to see the attached spec in action against the Mailman REST API, > go to http://www.mailripper.com/swagger-ui/index.html > > Give it a try at http://www.mailripper.com/swagger-ui/index.html - you are > welcome to change anything, it’s a test Mailman server and you can add or > delete anything - nothing you do will be a problem. > > There’s still a fair bit to do to finalise this but most of the API queries > are working - enough for you to see how it works. It looks interesting. I have a little experience with WADL with the Launchpad API. There was a lot of infrastructure built into lazr.restful to automatically generate the WADL, but it was so cumbersome that I was ecstatic to remove it all for restish (at the time). My big question is how to make sure that the swagger spec doesn't get out of date to the implementation. I definitely don't want to add a lot of cruft to the implementation - the light weight of the current falcon-based implementation is a huge benefit. It would be okay (maybe ideal) if some how the swagger spec was integrated with the core's test suite, so that at least we'd see failures if the API were modified (e.g. new resources and methods added) without the spec being similarly updated. Ultimately I think if it isn't much effort to keep up to date, and is useful to consumers of the API, it could be a good thing, but I don't really have any opinions about swagger as compared to alternatives. Cheers, -Barry _______________________________________________ Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/andrew.stuart%40supercoders.com.au Security Policy: http://wiki.list.org/x/QIA9 _______________________________________________ Mailman-Developers mailing list Mailman-Developers@python.org https://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://wiki.list.org/x/AgA3 Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/archive%40jab.org Security Policy: http://wiki.list.org/x/QIA9
