Swagger / OpenAPI Integration
How apikee automatically injects the security scheme into your API docs.
Swagger / OpenAPI Integration
apikee injects the ApikeeAuth API key security scheme into your OpenAPI spec automatically, across every supported framework.
What gets injected
components:
securitySchemes:
ApikeeAuth:
type: apiKey
in: header
name: x-api-key
description: >
apikee_ signed key with embedded claims (tenant, scopes, expiry).
Issue keys via POST /keys or the apikee.dev dashboard.
security:
- ApikeeAuth: []This causes Swagger UI to show a 🔒 lock icon on every endpoint and adds an Authorize button where users can paste their key and test the API.
Per-framework setup
SecuredFastAPI patches openapi() automatically — no extra code needed:
from apikee.fastapi import SecuredFastAPI
app = SecuredFastAPI(secrets=["..."])
# Swagger at /docs — every endpoint has the lockTo use the original FastAPI() and inject manually:
from fastapi import FastAPI
from apikee import Apikee
apikee = Apikee(secrets=["..."])
app = FastAPI()
apikee.configure_swagger(app) # patches app.openapi()
app.add_middleware(apikee.middleware)init_apikee calls _patch_flask_swagger automatically when flasgger is installed:
from apikee.flask import init_apikee
init_apikee(app, secrets=["..."], inject_swagger=True)For flask-openapi3:
from flask_openapi3 import OpenAPI
from apikee.flask import init_apikee
app = OpenAPI(__name__, info=info)
init_apikee(app, secrets=["..."])Call injectSwagger on your swagger-jsdoc spec object before passing it to swagger-ui-express:
import { injectSwagger } from 'apikee/express'
import swaggerJsdoc from 'swagger-jsdoc'
import swaggerUi from 'swagger-ui-express'
const spec = swaggerJsdoc(options)
injectSwagger(spec) // mutates spec in place
app.use('/docs', swaggerUi.serve, swaggerUi.setup(spec))Call injectFastifySwagger after registering @fastify/swagger:
import { injectFastifySwagger } from 'apikee/fastify'
import fastifySwagger from '@fastify/swagger'
await fastify.register(fastifySwagger, { openapi: { ... } })
injectFastifySwagger(fastify) // patches fastify.swagger()Hono doesn't have an official Swagger plugin yet. Add the scheme to your OpenAPI object manually:
app.get('/openapi.json', (c) => c.json({
...spec,
components: {
securitySchemes: {
ApikeeAuth: { type: 'apiKey', in: 'header', name: 'x-api-key' },
},
},
security: [{ ApikeeAuth: [] }],
}))The ApikeeOpenApiCustomizer bean is auto-configured when SpringDoc is on the classpath:
# application.yml — nothing else needed
apikee:
secrets: [ your-secret ]Swagger UI is at /swagger-ui.html. Every endpoint shows the lock.
Call AddApikeeSecurityDefinition() in your AddSwaggerGen block:
builder.Services.AddSwaggerGen(c => {
c.SwaggerDoc("v1", new() { Title = "My API", Version = "v1" });
c.AddApikeeSecurityDefinition(); // injects ApikeeAuth + global security
});Swagger UI is at /swagger. Every endpoint shows the lock.
Authorizing in Swagger UI
- Open
/docs(or/swagger-ui.html//swagger) - Click the Authorize button (🔒) at the top right
- Paste your
apikee_...key into theApikeeAuth (apiKey)field - Click Authorize, then Close
- All subsequent requests in Swagger UI will include the
x-api-keyheader
The key is stored in Swagger UI's session storage — it persists across page refreshes in the same tab but is cleared when the tab is closed.
Per-route security override
To exclude a specific route from the global security requirement (e.g. a public health endpoint):
# FastAPI — pass empty security list
@app.get("/health", security=[])
def health():
return {"status": "ok"}// Express swagger-jsdoc — annotate the route
/**
* @openapi
* /health:
* get:
* security: []
* summary: Health check
*/
app.get('/health', (_, res) => res.json({ status: 'ok' }))