To work around this problem, I changed the security schemes to describe a single API key field (it’s a query parameter). This is well understood by all tools, and also most of them will just pick the first one when multiple are specified. Then I added the API secret field as a required parameter to all the endpoints.
This isn’t an ideal situation, because the secret really is part of the auth, not a parameter. However I did find that it helped not only my Postman import, but also use of Prism as a mock server, and that some documentation tools rendered the required fields for each endpoint more clearly.
As things stand, I have a single security scheme listed in the
securitySchemes: apiKey: type: apiKey name: api_key in: query description: >- You can find your API key in your Nexmo account [developer dashboard](https://dashboard.nexmo.com/)
Then for each endpoint, I added the additional parameter (described in the
parameters: section of
components: and using a
$ref). This is perhaps less formally correct, but more working, than what I had before – so I’m living with it for now.
If you want to see the spec in action, it’s here: https://github.com/Nexmo/api-specification/blob/master/definitions/verify.yml and if you have any better ideas, I’d love to hear them!
Also published on Medium.