Add Components.security_scheme

[lafrech]

Addresses #245.

https://swagger.io/docs/specification/components/
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#componentsObject
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject

https://swagger.io/docs/specification/authentication/
https://swagger.io/docs/specification/2-0/authentication/

[lafrech]

I realize there is not much added value in this. It abstract the location of the component w.r.t OpenAPI version but the content differs in both versions and there is no need for a helper, so passing the dict manually at APISpec instantiation as done in test_core.py is not much worse:

https://github.com/marshmallow-code/apispec/blob/dev/tests/test_core.py#L51

BTW, if we merge this, it could be worth finding a better example in test_core.py or adding a note saying the Component.security_scheme method is the preferred way to register security schemes.

[lafrech]

I find it weird to pass the dict as kwargs rather than as a positional argument. I did this to expose an interface similar as parameter or response.

Maybe we could change that in all component registration methods, I mean change

    def parameter(self, param_id, location, **kwargs):
    def response(self, ref_id, **kwargs):

into

    def parameter(self, param_id, location, parameter, **kwargs):
    def response(self, ref_id, response, **kwargs):

but after a quick glance I realized it has consequences on the plugin interface (helpers signature), and maybe more, so I left it as is for now.

Since there is no helper and therefore no kwargs to pass, we could use a positional argument here, but it would be less consistent. And we'd have to break that if someone ever comes up with a security scheme helper.

[sloria]

I'm good with this as is.

Even though the use case is supported by passing kwargs to APISpec, this is consistent with the rest of the API.

[lafrech]

docs/special_topics.rst needs to be updated.