Using Swagger UI to Test OAuth2 Authorization Code Flow in Your API Docs

Problem: Testing protected endpoints in Swagger UI

When an API endpoint requires OAuth2 Authorization Code flow, the default Swagger UI interface shows no way to attach a token, so the "Try it out" button returns 401 Unauthorized and you cannot verify the implementation locally.

Solution: Declare an OAuth2 Authorization Code security scheme

OpenAPI lets you define a security scheme under components.securitySchemes and reference it in operations. Swagger UI reads this definition, renders an Authorize button, performs the redirect‑based flow, and stores the resulting access token for subsequent requests.

Minimal OpenAPI YAML example

openapi: 3.0.3
info:
  title: Petstore API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List pets
      security:
        - petstore_auth:
            - pets.read
      responses:
        '200':
          description: A JSON array of pet names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
components:
  securitySchemes:
    petstore_auth:
      type: oauth2
      flow: authorizationCode
      authorizationUrl: https://auth.example.com/authorize
      tokenUrl: https://auth.example.com/token
      scopes:
        pets.read: Read access to pets
        pets.write: Write access to pets

Running Swagger UI locally

Place the above YAML in a file named openapi.yaml. Start Swagger UI with Docker (you need permission to run Docker containers):

docker run -p 8080:8080 -v "$(pwd):/swagger-ui" swaggerapi/swagger-ui

Open http://localhost:8080 in a browser. You should see the Swagger UI page and, after a moment, an Authorize button in the top‑right corner.

Risk: If the authorization server does not allow Swagger UI’s origin (http://localhost:8080) in its CORS policy, the token exchange request will be blocked and you will receive a network error instead of a token.


Completing the authorization dance

Click the Authorize button.
In the modal, ensure the petstore_auth scheme is selected.
Enter the client ID (if your auth server requires it) and optionally set the scopes you want.
Click Authorize again; Swagger UI redirects to the authorizationUrl you defined.
Log in to the test identity provider and approve the consent screen.
After the redirect back to Swagger UI, the modal closes and the button shows a green lock, indicating the token is stored.


Making a test call
Now expand the GET /pets operation and click Try it out. The Execute request will include an Authorization: Bearer <token> header. If the token is valid, you receive a 200 response; otherwise you see 401 or 403.


Trade‑offs and limitations

Relies on the browser’s ability to follow redirects and handle CORS; a misconfigured auth server will break the flow.
Swagger UI does not automatically refresh expired tokens; you must re‑authorize manually or add a custom token‑refresh handler.
The flow works best with authorization servers that support PKCE or allow confidential clients; public‑client‑only servers may require extra configuration.


Actionable closing
To verify that security is truly enforced:

After a successful request, log out of the identity provider or revoke the token via the admin console.
Return to Swagger UI and click Try it out again on the same endpoint.
Observe that the response is 401 Unauthorized, confirming that the stored token is no longer valid and that Swagger UI is attaching it to requests.

With the OAuth2 security scheme in place, you can now develop, test, and document protected endpoints without leaving the API documentation UI.