Swagger UI provides a “Try it out” feature that lets users submit actual requests. To actually submit requests that are authorized by your API server, the spec must contain security information that will authorize the request. The
security object specifies the security or authorization protocol used when submitting requests.
REST APIs can use a number of different security approaches to authorize requests. I explored the most common authorization methods in Documenting authentication and authorization requirements. Swagger UI supports four authorization schemes:
In this tutorial, I’ll explain the API key method, as it’s the most common and it’s what I’m most familiar with. If your API uses OAuth 2.0 or another method, you’ll need to read the Security Scheme information for details on how to configure it. However, all the security methods largely follow the same pattern.
The sample Mashape weather API we’re using in this course uses an API key passed in the request header (
X-Mashape-Key: 123456789). If you submit a request without this header (and without a valid API key), the server denies the request.
At the root level of your OpenAPI document, add a
security object that defines the global method we’re using for security:
security: - Mashape-Key: 
Mashape-Key is the arbitrary name we gave to this security scheme in our
securitySchemes object. We could have named it anything. We’ll define
All paths will use the
Mashape-Key security method by default unless it’s overridden by a value at the
path object level. For example, at the path level we could overwrite the global security method as follows:
/weatherdata: get: ... security: - Some-Other-Key: 
weatherdata path would use the
Some-Other-Key security method, while all other paths would use the globally declared security,
components: ... securitySchemes: Mashape-Key: type: apiKey description: "The API authorizes requests through an API key in your header. Enter your Mashape key here. If you don't have an API key, for testing purposes you can use `EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p`." name: X-Mashape-Key in: header
Properties you can use in the
securitySchemes object include the following:
type: The type of authorization —
description: A description of your security method. In Swagger UI, this description appears in the Authorization modal (see screenshot below). CommonMark Markdown is allowed.
name: The name of the header value submitted in the request. Used only for
in: Specifies where the security key is applied. Options are
cookie. Used only for
scheme. Used with
bearerFormat. Used with
flows(object): Used with
openIdConnectUrl: Used with
In the Swagger UI, you see the
description and other security details in the Authorization modal (which appears when you click the Authorization button):
After users enter an API key and clicks Authorize, the authorization method is set for as many requests as they want to make. Only when users refresh the page does the authorization session expire.
When you submit a request, Swagger UI shows you the curl request that is submitted. For example, after executing a weather request, the curl is as follows:
curl -X GET "https://simple-weather.p.mashape.com/weather?lat=37.3708698&lng=-122.037593" -H "accept: text/plain" -H "X-Mashape-Key: EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p"
-H "X-Mashape-Key: EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p" indicates that a header is being sent with the API key. (For more on curl, see Make a curl call.)
If you have security correctly configured but the requests are being rejected, it could be due to a CORS (cross-origin resource sharing) issue. CORS is a security measure that websites implement to make sure other scripts and processes cannot take their content through requests from remote servers. See CORS Support in Swagger UI’s documentation for details.
62/92 pages complete. Only 30 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson