Step 6: The security object (OpenAPI tutorial)
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.
- Which security scheme?
- API key authorization
- Security object
- Referencing the security scheme in components
- Appearance in Swagger UI
- Checking to see if authorization works
- Troubleshooting issues
Which security scheme?
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:
- API key
- OAuth 2.0
- Open ID Connect
In this step of the OpenAPI tutorial, we’ll use the API key approach, since this is what the OpenWeatherMap API uses. 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.
API key authorization
The sample OpenWeatherMap API we’re using in this course uses an API key passed in the URL’s query string (rather than the header). If you submit a request without the API key in the query string (or without a valid API key), the server denies the request. For details on the OpenWeatherMap’s authorization model, see How to start.
At the root level of your OpenAPI document, we add a
security object that defines the global method for our security:
security: - app_id: 
app_id 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
app_id 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:
/current: get: ... security: - some_other_key: 
weather path would use the
some_other_key security method, while all other paths would use the globally declared security,
Referencing the security scheme in components
components: ... securitySchemes: app_id: type: apiKey description: API key to authorize requests. If you don't have an OpenWeatherMap API key, use `fd4698c940c6d1da602a70ac34f0b147`. name: appid in: query
Properties you can use for each item 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
Appearance in Swagger UI
In Swagger Editor, insert the following at the root level:
security: - app_id: 
And insert the
securitySchemes object into
components (indented at the same level as
components: parameters: ... responses: ... securitySchemes: app_id: type: apiKey description: API key to authorize requests. If you don't have an OpenWeatherMap API key, use `fd4698c940c6d1da602a70ac34f0b147`. name: appid in: query
You’ll see an “Authorize” button appear in the Swagger UI display.
When you click the Authorization button, the
description and other security details appear:
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.
Checking to see if authorization works
Now that we’ve added authorization, let’s test it out. In the Swagger Editor (the right pane), click the Authorize button, paste the sample API key shown in the description into the Value field and click Authorize. Then click Close to close the authorization modal.
Then in the Current Weather Data section, expand the GET weather endpoint and click Try it out. In the zip field, enter your zip code and country abbreviation (
e.g., 95050,us), and then click Execute.
When you execute the 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://api.openweathermap.org/data/2.5/weather?zip=95050&units=imperial&lang=en&mode=json&appid=fd4698c940c6d1da602a70ac34f0b147" -H "accept: application/json"
&appid=fd4698c940c6d1da602a70ac34f0b147" indicates that the API key is being included in the query string, so the request will be authorized.
However, in this sample scenario, OpenWeatherMap doesn’t seem to allow requests from Swagger Editor, so you’ll see “TypeError: Failed to fetch” as the response.
If you copy the curl submitted and paste it into the command line, you’ll see a successful response:
With the successful message from the command line, you know that Swagger is submitting a successful request but the API server is rejecting it. See the next section for Troubleshooting tips.
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.
Host URL issues:
Another reason requests might be rejected is due to the host from your test server. Some APIs (like Aeris Weather) require you to create an App ID that’s based on the host URL where you’ll be executing requests. If the host URL you registered is
http://mysite.com but you’re submitting the test from
https://editor.swagger.io/, the API server will reject the requests.
63/108 pages complete. Only 45 more pages to go...
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.