search

marshmallow-code / apispec

A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification)..
https://apispec.readthedocs.io/
MIT License
1.18k stars 177 forks source link

Security scheme documentation #918

Closed MattoElGato closed 4 months ago

MattoElGato commented 5 months ago

Hi,

I believe the optional security suite example provided in apispec/docs/index.rst requires the line security=[{"ApiKeyAuth": []}] added at line 37. If you don't add this line then the authorization header isn't added to any requests made from the Swagger UI.

Posting here (rather than forking/PR) as I'm not sure if there's a more elegant way of achieving this as part of the block at lines 51-53, but the above is functional.

lafrech commented 4 months ago

The example isn't wrong because the scheme is used in the random_pet resource defined below. What you suggest is to add it globally, which is another user case.

This is just an example among many possibilities. A comprehensive coverage of all cases is not something we can reasonably aim at.

Maybe we shouldn't mention security schemes at all at this point of the docs, then.

Closing for now, but thanks for bringing this up in a constructive way.