[Mailman-Developers] REST API first pass at Swagger spec

[Andrew Stuart]

" as soon as Andrew loses interest in keeping it up to date.”

;-) I was never interested in keeping it up to date in the first place but I can’t stand doing development without API documentation, a necessary first step to coding to the API.

I do like your idea about changes to the API not being complete until they have been implemented into the JSON spec.

On 12 Jan 2015, at 12:46 pm, Stephen J. Turnbull <stephen at xemacs.org> wrote:

Barry Warsaw writes:

> My big question is how to make sure that the swagger spec doesn't
> get out of date to the implementation.

Doesn't Andrew's use case answer that?  I mean, if the Swagger spec is
out of date, the tests based on it should fail.  If the tests don't
fail, they're incomplete anyway, and that's a different problem that
no spec language can solve for you.

As a matter of process, if Swagger is readable enough, we make it
*the* spec, and you don't accept pull requests for the REST
implementation without a patch to the spec.  If Swagger isn't usable
in that fashion, I suppose it will go away again like WADL as soon as
Andrew loses interest in keeping it up to date. ;-)
_______________________________________________
Mailman-Developers mailing list
Mailman-Developers at 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