wordnik/swagger-ui — pull request #194 by szywon (2013-04-23 10:46:08+00:00)
Title: OAuth support

This is more of an discussion opener on how to achieve that while
being compatibile with the spec because it introduces some breaking
changes regarding POST data encoding.

This commit contains only source changes.

Non-breaking changes:

- Added `headersGen` field to configuration options (details below)
- `api_key` field doubles as consumer_key when `consumer_secret` is
filled (putting `consumer_secret` in means triggering OAuth mode
on).
- Added "How Are You? API" button to ease testing of the OAuth
implementation (test with "demo" `patient_id` field).
- Imported ohauth library.
- Whitespace cleanups (I can revert that if you wish to preserve
those).

Breaking changes:

- `body` params are sent using `application/x-www-form-urlencoded`
(details below) and because of that the type selectors for these
fields are disabled.

## headersGen option:

To allow any kind of request signing, a method to generate headers
dynamically (just before sending) was needed. `headersGen` option is
meant to hold a function that receives jQuery AJAX configuration
object and returns an object holding generated headers. For OAuth
it'd be something like:

new SwaggerUi({
...
headersGen: function (ajax) {
return { Authorization: "OAuth ..." };
}
...
});

## POST data as application/x-www-form-urlencoded:

The OAuth 1.0 specification requires POST data to be encoded in the
form-urlencoded form (as in query strings) in order to be a part of
the signed data. Otherwise it's ought to be omitted. Relevant section:
http://tools.ietf.org/html/rfc5849#section-3.4.1.3.1

Because of that we can't use multipart encoding for POST data with
OAuth. So to get expected behaviour, instead of passing one `body`
field, they're collected and then encoded with
`jQuery.param()`. (`OperationView.coffee`, lines 117-122)

I'd be happy to receive any comments and suggestions on how to improve this code.