Why is my Swagger documentation not showing auth correctly?

Swagger auth usually “doesn’t show correctly” for one of a few common reasons. The exact fix depends on whether you’re using OpenAPI 3 / Swagger UI and what backend framework you have, but here’s the usual checklist.

Common causes

1) Security scheme is not defined correctly

You need a security scheme in the OpenAPI config, not just auth middleware in your app.

Examples:

• Bearer token / JWT → type: http, scheme: bearer, bearerFormat: JWT
• API key → type: apiKey, in: header, name: X-API-Key
• Basic auth → type: http, scheme: basic

If this is missing, Swagger UI won’t know how to render the auth button properly.

---

2) You defined the scheme, but didn’t apply it to endpoints

Swagger needs both:

• a global security definition, or
• per-route security requirements

If you only define the scheme but never attach it, endpoints may appear unauthenticated.

---

3) OpenAPI version mismatch

A lot of older examples use Swagger 2.0 syntax, but newer tools expect OpenAPI 3.

For example:

OpenAPI 3 bearer auth

openapi: 3.0.3
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

Swagger 2.0 equivalent

securityDefinitions:
  bearerAuth:
    type: apiKey
    name: Authorization
    in: header
security:
  - bearerAuth: []

Mixing these styles can break display.

---

4) Missing Authorization header format

If you’re using Bearer auth, Swagger UI often expects the value in this format:

Bearer YOUR_TOKEN

Some setups auto-add Bearer , others don’t. If you only paste the raw token, auth may fail even though UI looks right.

---

5) CORS / proxy strips the header

If Swagger UI tries requests but auth isn’t reaching the backend, a proxy or CORS config may be stripping the Authorization header.

Check:

• reverse proxy config
• CORS allowedHeaders
• Authorization allowed in API gateway / load balancer

---

6) Nested routes or decorators override security

In frameworks like NestJS, FastAPI, Spring, etc., route-level decorators may:

• override global security
• mark endpoints as public
• omit metadata used by Swagger generation

So the UI might show some routes with lock icons and others without.

---

Example of correct OpenAPI 3 bearer setup

openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      security:
        - bearerAuth: []
      responses:
        "200":
          description: OK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

---

What to check in your app

If you’re using a framework, verify:

1. Swagger/OpenAPI config includes a security scheme
2. Endpoints include security requirements
3. You’re using the correct OpenAPI version
4. The auth header is being sent as expected
5. Your proxy/CORS doesn’t remove Authorization

---

If you want, I can help more precisely

Paste:

• your Swagger/OpenAPI config
• the framework you’re using
• one example endpoint

and I’ll point out exactly why auth isn’t showing correctly.