On Jan 12, 2015, at 12:47 PM, Andrew Stuart wrote: >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.
Agreed. >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. MM3 does not have a static file server, but I think we could serve the file as an API endpoint. Perhaps /<api>/api-docs.json or if that's difficult to implement, /<api>/system/api-docs.json. >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 worry a little bit about the extra work to keep it up-to-date when I change the API, but maybe it won't be so bad in practice. I wonder if there are any automated testing tools that can be integrated in the test suite. I.e. something that grabs the api-docs.json and then makes calls against the API to verify endpoints, arguments, and return values. Do you know of any such tool? >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. Sounds good! 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
