Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Swagger UI or Swagger Editor cannot call my API or load my spec because of CORS

ErrorNo 'Access-Control-Allow-Origin' header is present on the requested resource.

Short answer

Swagger UI and Swagger Editor run in the browser, so CORS applies twice: to your API endpoints when you press Try it out, and to the spec file when it is loaded from another origin. Enable CORS on both, allow every request header Swagger UI sends, or serve Swagger UI from the same origin as the API.

  • Applies to Swagger UI in the browser, Swagger Editor, OpenAPI documents, Express with the cors package, current Chrome and Firefox
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the server for the two things Swagger needs, with an Origin header like the one the browser sends: the spec file and one API endpoint. Look for Access-Control-Allow-Origin in each answer. The one without it is the one that is blocked.

    curl -s -D - -o /dev/null https://api.example.com/openapi.json -H "Origin: https://docs.example.com"
    curl -s -D - -o /dev/null https://api.example.com/v1/pets -H "Origin: https://docs.example.com"
  2. 2Match what you see, then jump to its fix

    1. 1Try it out ends in an error, and the console says No 'Access-Control-Allow-Origin' header is presentThe API endpoints send no CORS headersFix
    2. 2The page or the editor cannot load the definition from a URL, and the console shows the same missing-header error for the spec URL, not for an API callThe spec file or a $ref document is served without CORS headersFix
    3. 3Calls without auth work, but endpoints that need Authorization, an API key header or another custom header failA request header that Swagger UI sends is not in Access-Control-Allow-HeadersFix

What does the error look like?

  • No 'Access-Control-Allow-Origin' header is present on the requested resource.
  • Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource (Reason: CORS request did not succeed)
  • Try it out fails and the spec cannot be imported from a URL, while curl returns the data without trouble

Cause 1 of 3

The API endpoints send no CORS headers

1Check

Swagger UI calls your API from the browser, so the API has to allow the origin Swagger UI is served from. Run the second request from the first step and read its headers: you want Access-Control-Allow-Origin, and for non-simple calls Access-Control-Allow-Methods including OPTIONS.

curl -s -D - -o /dev/null -X OPTIONS https://api.example.com/v1/pets -H "Origin: https://docs.example.com" -H "Access-Control-Request-Method: POST"

2Fix

Enable CORS in your server or framework; how depends on the stack. If you cannot change the API, serve Swagger UI from the same host and port as the API, or put a proxy in front that adds the headers. Example for Express:

const cors = require('cors');

app.use(cors({
  origin: 'https://docs.example.com',
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
}));

3Verify

The endpoint now answers with the header, and Try it out returns a real response.

curl -s -D - -o /dev/null https://api.example.com/v1/pets -H "Origin: https://docs.example.com" | grep -i access-control

Confirmed by swagger.io

Did this fix it?

Cause 2 of 3

The spec file or a $ref document is served without CORS headers

1Check

Swagger UI downloads the definition in the browser, and SwaggerEditor, which is built from Swagger UI plugins, can load a remote definition by URL in the same way. If the file lives on another origin, that host must send the CORS headers, and so must every externally referenced document. Test the spec URL.

curl -s -D - -o /dev/null https://api.example.com/openapi.json -H "Origin: https://editor.example.com" | grep -i access-control

2Fix

Enable CORS on the route or bucket that serves the definition, or serve the file from the same origin as Swagger UI.

app.get('/openapi.json', cors({ origin: 'https://editor.example.com' }), (req, res) => {
  res.json(spec);
});

3Verify

The spec URL now returns Access-Control-Allow-Origin, and the editor imports it.

curl -s -D - -o /dev/null https://api.example.com/openapi.json -H "Origin: https://editor.example.com" | grep -i allow-origin

Confirmed by swagger.io

Did this fix it?

Cause 3 of 3

A request header that Swagger UI sends is not in Access-Control-Allow-Headers

1Check

Only the header names listed in Access-Control-Allow-Headers may be sent by Swagger UI. Custom headers you declare as parameters in the spec must be listed as well. Ask for the preflight with the header names Swagger will send and read the answer.

curl -s -D - -o /dev/null -X OPTIONS https://api.example.com/v1/pets -H "Origin: https://docs.example.com" -H "Access-Control-Request-Method: GET" -H "Access-Control-Request-Headers: authorization,api_key" | grep -i access-control

2Fix

List every header name the spec uses, for example Content-Type, api_key and Authorization.

app.use(cors({
  origin: 'https://docs.example.com',
  allowedHeaders: ['Content-Type', 'api_key', 'Authorization'],
}));

3Verify

The preflight answer now contains Access-Control-Allow-Headers with those names, and the authorized call works in Try it out.

curl -s -D - -o /dev/null -X OPTIONS https://api.example.com/v1/pets -H "Origin: https://docs.example.com" -H "Access-Control-Request-Method: GET" -H "Access-Control-Request-Headers: authorization,api_key" | grep -i allow-headers

Confirmed by swagger.io

Did this fix it?

How do I stop it coming back?

  • Treat the spec URL and the API as two separate things to test for CORS, because each can fail on its own.
  • Whenever you add a header parameter to the spec, add the same name to the server's allowed headers.
  • Do not trust a third-party CORS tester alone: one common tester reports success even when Access-Control-Allow-Headers is missing, so read the headers with curl.
  • Prefer serving Swagger UI from the application it documents, so no CORS rule is needed at all.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

The browser blocks your API response: no Access-Control-Allow-Origin header

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://api.example.com/orders. (Reason: CORS header 'Access-Control-Allow-Origin' missing).

The browser received the response but refused to hand it to your script, because it did not carry an Access-Control-Allow-Origin header naming the page's origin.

4 causes, each with a fix

Web apps

A POST to a Google Apps Script web app returns 405 or a CORS error

Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Apps Script web apps run doPost for POST and doGet for GET, and the Apps Script guides describe no other entry points.

3 causes, each with a fix

Web apps

A Chrome extension content script cannot read another site's response

Access to fetch at 'https://api.example.com/price' from origin 'https://shop.example.net' has been blocked by CORS policy

Since Chrome 85 a content script's request is treated as a request from the web page it runs in, so the page's CORS rules apply and the extension's host permissions do not help.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.