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/archive%40jab.org Security Policy: http://wiki.list.org/x/QIA9
