mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 20:47:44 +00:00
572 lines
26 KiB
TypeScript
572 lines
26 KiB
TypeScript
import type { Extension } from "./extensions";
|
|
|
|
/**
|
|
* -----
|
|
* Security Scheme Object
|
|
* -----
|
|
*
|
|
* Defines a security scheme that can be used by the operations.
|
|
* Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter),
|
|
* OAuth2's common flows (implicit, password, application and access code) as defined in RFC6749,
|
|
* and OpenID Connect Discovery.
|
|
*
|
|
* The Security Scheme Object defines a security scheme that can be used by the operations.
|
|
* It supports various authentication methods including HTTP authentication, API keys,
|
|
* OAuth2 flows, and OpenID Connect Discovery.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `type` - Required The type of the security scheme
|
|
* @property `description` - Optional A short description for security scheme
|
|
* @property `name` - Optional The name of the header, query or cookie parameter to be used
|
|
* @property `in` - Optional The location of the API key
|
|
* @property `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header
|
|
* @property `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted
|
|
* @property `flows` - Optional An object containing configuration information for the flow types supported
|
|
* @property `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values
|
|
* @property `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* The `type` field is required. The `name` and `in` fields are required for apiKey type.
|
|
* In OpenAPI 3.0.1+, the `bearerFormat` field was clarified to be a hint to the client
|
|
* about how the bearer token is formatted, and the `openIdConnectUrl` field was clarified
|
|
* to be a URL that can be used to discover OAuth2 configuration values.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (API key):
|
|
* ```ts
|
|
* const securityScheme: SecurityScheme = {
|
|
* type: "apiKey",
|
|
* in: "header",
|
|
* name: "X-API-Key"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (OAuth2):
|
|
* ```ts
|
|
* const securityScheme: SecurityScheme = {
|
|
* type: "oauth2",
|
|
* flows: {
|
|
* authorizationCode: {
|
|
* authorizationUrl: "https://example.com/oauth/authorize",
|
|
* tokenUrl: "https://example.com/oauth/token",
|
|
* scopes: {
|
|
* "read": "Read access",
|
|
* "write": "Write access"
|
|
* }
|
|
* }
|
|
* }
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (HTTP Bearer):
|
|
* ```ts
|
|
* const securityScheme: SecurityScheme = {
|
|
* type: "http",
|
|
* scheme: "bearer",
|
|
* bearerFormat: "JWT"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (OpenID Connect):
|
|
* ```ts
|
|
* const securityScheme: SecurityScheme = {
|
|
* type: "openIdConnect",
|
|
* openIdConnectUrl: "https://example.com/.well-known/openid_configuration"
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface SecurityScheme extends Extension {
|
|
/**
|
|
* The type of the security scheme. This field is required.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - type} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - type} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - type} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - type} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - type} |
|
|
* @property `type` - Required The type of the security scheme
|
|
*
|
|
* @example "apiKey"
|
|
* @example "http"
|
|
* @example "oauth2"
|
|
* @example "openIdConnect"
|
|
*/
|
|
type: "apiKey" | "http" | "oauth2" | "openIdConnect";
|
|
|
|
/**
|
|
* A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - description} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - description} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - description} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - description} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - description} |
|
|
* @property `description` - Optional A short description for security scheme
|
|
*
|
|
* @example "API key authentication"
|
|
* @example "OAuth 2.0 authentication"
|
|
*/
|
|
description?: string;
|
|
|
|
/**
|
|
* The name of the header, query or cookie parameter to be used.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - name} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - name} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - name} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - name} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - name} |
|
|
* @property `name` - Optional The name of the header, query or cookie parameter to be used
|
|
*
|
|
* @example "X-API-Key"
|
|
* @example "Authorization"
|
|
*/
|
|
name?: string;
|
|
|
|
/**
|
|
* The location of the API key. Valid values are "query", "header" or "cookie".
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - in} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - in} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - in} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - in} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - in} |
|
|
* @property `in` - Optional The location of the API key
|
|
*
|
|
* @example "query"
|
|
* @example "header"
|
|
* @example "cookie"
|
|
*/
|
|
in?: "query" | "header" | "cookie";
|
|
|
|
/**
|
|
* The name of the HTTP Authorization scheme to be used in the Authorization header.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - scheme} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - scheme} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - scheme} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - scheme} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - scheme} |
|
|
* @property `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header
|
|
*
|
|
* @example "bearer"
|
|
* @example "basic"
|
|
*/
|
|
scheme?: string;
|
|
|
|
/**
|
|
* A hint to the client to identify how the bearer token is formatted.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - bearerFormat} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - bearerFormat} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - bearerFormat} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - bearerFormat} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - bearerFormat} |
|
|
* @property `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted
|
|
*
|
|
* @example "JWT"
|
|
* @example "Bearer"
|
|
*/
|
|
bearerFormat?: string;
|
|
|
|
/**
|
|
* An object containing configuration information for the flow types supported.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - flows} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - flows} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - flows} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - flows} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - flows} |
|
|
* @property `flows` - Optional An object containing configuration information for the flow types supported
|
|
*
|
|
* @example { authorizationCode: { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token" } }
|
|
*/
|
|
flows?: OAuthFlows;
|
|
|
|
/**
|
|
* OpenId Connect URL to discover OAuth2 configuration values.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-scheme-object | OpenAPI 3.0.4 Security Scheme Object - openIdConnectUrl} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-scheme-object | OpenAPI 3.0.3 Security Scheme Object - openIdConnectUrl} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-scheme-object | OpenAPI 3.0.2 Security Scheme Object - openIdConnectUrl} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-scheme-object | OpenAPI 3.0.1 Security Scheme Object - openIdConnectUrl} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-scheme-object | OpenAPI 3.0.0 Security Scheme Object - openIdConnectUrl} |
|
|
* @property `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values
|
|
*
|
|
* @example "https://example.com/.well-known/openid_configuration"
|
|
*/
|
|
openIdConnectUrl?: string;
|
|
}
|
|
|
|
/**
|
|
* -----
|
|
* OAuth Flows Object
|
|
* -----
|
|
*
|
|
* Allows configuration of the supported OAuth Flows.
|
|
*
|
|
* The OAuth Flows Object allows configuration of the supported OAuth Flows. Each property
|
|
* represents a specific OAuth flow type and contains configuration details for that flow.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flows-object | OpenAPI 3.0.4 OAuth Flows} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flows-object | OpenAPI 3.0.3 OAuth Flows} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flows-object | OpenAPI 3.0.2 OAuth Flows} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flows-object | OpenAPI 3.0.1 OAuth Flows} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flows-object | OpenAPI 3.0.0 OAuth Flows} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `implicit` - Optional Configuration for the OAuth Implicit flow
|
|
* @property `password` - Optional Configuration for the OAuth Resource Owner Password flow
|
|
* @property `clientCredentials` - Optional Configuration for the OAuth Client Credentials flow
|
|
* @property `authorizationCode` - Optional Configuration for the OAuth Authorization Code flow
|
|
* @property `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* All OAuth flow configurations are optional. At least one flow type should be provided
|
|
* for a complete OAuth2 security scheme configuration.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (authorization code flow):
|
|
* ```ts
|
|
* const flows: OAuthFlows = {
|
|
* authorizationCode: {
|
|
* authorizationUrl: "https://example.com/oauth/authorize",
|
|
* tokenUrl: "https://example.com/oauth/token",
|
|
* scopes: {
|
|
* "read": "Read access to resources",
|
|
* "write": "Write access to resources"
|
|
* }
|
|
* }
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (multiple flows):
|
|
* ```ts
|
|
* const flows: OAuthFlows = {
|
|
* implicit: {
|
|
* authorizationUrl: "https://example.com/oauth/authorize",
|
|
* scopes: {
|
|
* "read": "Read access"
|
|
* }
|
|
* },
|
|
* clientCredentials: {
|
|
* tokenUrl: "https://example.com/oauth/token",
|
|
* scopes: {
|
|
* "admin": "Administrative access"
|
|
* }
|
|
* }
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface OAuthFlows extends Extension {
|
|
/**
|
|
* Configuration for the OAuth Implicit flow.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flows-object | OpenAPI 3.0.4 OAuth Flows Object - implicit} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flows-object | OpenAPI 3.0.3 OAuth Flows Object - implicit} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flows-object | OpenAPI 3.0.2 OAuth Flows Object - implicit} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flows-object | OpenAPI 3.0.1 OAuth Flows Object - implicit} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flows-object | OpenAPI 3.0.0 OAuth Flows Object - implicit} |
|
|
* @property `implicit` - Optional Configuration for the OAuth Implicit flow
|
|
*
|
|
* @example { authorizationUrl: "https://example.com/oauth/authorize", scopes: { read: "Read access" } }
|
|
*/
|
|
implicit?: OAuthFlow;
|
|
|
|
/**
|
|
* Configuration for the OAuth Resource Owner Password flow.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flows-object | OpenAPI 3.0.4 OAuth Flows Object - password} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flows-object | OpenAPI 3.0.3 OAuth Flows Object - password} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flows-object | OpenAPI 3.0.2 OAuth Flows Object - password} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flows-object | OpenAPI 3.0.1 OAuth Flows Object - password} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flows-object | OpenAPI 3.0.0 OAuth Flows Object - password} |
|
|
* @property `password` - Optional Configuration for the OAuth Resource Owner Password flow
|
|
*
|
|
* @example { tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } }
|
|
*/
|
|
password?: OAuthFlow;
|
|
|
|
/**
|
|
* Configuration for the OAuth Client Credentials flow.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flows-object | OpenAPI 3.0.4 OAuth Flows Object - clientCredentials} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flows-object | OpenAPI 3.0.3 OAuth Flows Object - clientCredentials} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flows-object | OpenAPI 3.0.2 OAuth Flows Object - clientCredentials} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flows-object | OpenAPI 3.0.1 OAuth Flows Object - clientCredentials} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flows-object | OpenAPI 3.0.0 OAuth Flows Object - clientCredentials} |
|
|
* @property `clientCredentials` - Optional Configuration for the OAuth Client Credentials flow
|
|
*
|
|
* @example { tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } }
|
|
*/
|
|
clientCredentials?: OAuthFlow;
|
|
|
|
/**
|
|
* Configuration for the OAuth Authorization Code flow.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flows-object | OpenAPI 3.0.4 OAuth Flows Object - authorizationCode} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flows-object | OpenAPI 3.0.3 OAuth Flows Object - authorizationCode} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flows-object | OpenAPI 3.0.2 OAuth Flows Object - authorizationCode} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flows-object | OpenAPI 3.0.1 OAuth Flows Object - authorizationCode} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flows-object | OpenAPI 3.0.0 OAuth Flows Object - authorizationCode} |
|
|
* @property `authorizationCode` - Optional Configuration for the OAuth Authorization Code flow
|
|
*
|
|
* @example { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token", scopes: { read: "Read access" } }
|
|
*/
|
|
authorizationCode?: OAuthFlow;
|
|
}
|
|
|
|
/**
|
|
* -----
|
|
* OAuth Flow Object
|
|
* -----
|
|
*
|
|
* Configuration details for a supported OAuth Flow.
|
|
*
|
|
* The OAuth Flow Object contains configuration details for a specific OAuth flow.
|
|
* Different OAuth flows require different combinations of URLs and parameters.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flow-object | OpenAPI 3.0.4 OAuth Flow} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flow-object | OpenAPI 3.0.3 OAuth Flow} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flow-object | OpenAPI 3.0.2 OAuth Flow} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flow-object | OpenAPI 3.0.1 OAuth Flow} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flow-object | OpenAPI 3.0.0 OAuth Flow} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `authorizationUrl` - Optional The authorization URL to be used for this flow
|
|
* @property `tokenUrl` - Optional The token URL to be used for this flow
|
|
* @property `refreshUrl` - Optional The URL to be used for obtaining refresh tokens
|
|
* @property `scopes` - Required The available scopes for the OAuth2 security scheme
|
|
* @property `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* The `scopes` field is required for all OAuth flows. The `authorizationUrl` is required for
|
|
* `implicit` and `authorizationCode` flows. The `tokenUrl` is required for `password`,
|
|
* `clientCredentials`, and `authorizationCode` flows.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (authorization code flow):
|
|
* ```ts
|
|
* const flow: OAuthFlow = {
|
|
* authorizationUrl: "https://example.com/oauth/authorize",
|
|
* tokenUrl: "https://example.com/oauth/token",
|
|
* scopes: {
|
|
* "read": "Read access to resources",
|
|
* "write": "Write access to resources"
|
|
* }
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (implicit flow):
|
|
* ```ts
|
|
* const flow: OAuthFlow = {
|
|
* authorizationUrl: "https://example.com/oauth/authorize",
|
|
* scopes: {
|
|
* "read": "Read access",
|
|
* "write": "Write access"
|
|
* }
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (client credentials flow):
|
|
* ```ts
|
|
* const flow: OAuthFlow = {
|
|
* tokenUrl: "https://example.com/oauth/token",
|
|
* scopes: {
|
|
* "admin": "Administrative access"
|
|
* }
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface OAuthFlow extends Extension {
|
|
/**
|
|
* The authorization URL to be used for this flow. This MUST be in the form of a URL.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flow-object | OpenAPI 3.0.4 OAuth Flow Object - authorizationUrl} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flow-object | OpenAPI 3.0.3 OAuth Flow Object - authorizationUrl} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flow-object | OpenAPI 3.0.2 OAuth Flow Object - authorizationUrl} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flow-object | OpenAPI 3.0.1 OAuth Flow Object - authorizationUrl} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flow-object | OpenAPI 3.0.0 OAuth Flow Object - authorizationUrl} |
|
|
* @property `authorizationUrl` - Optional The authorization URL to be used for this flow
|
|
*
|
|
* @example "https://example.com/oauth/authorize"
|
|
* @example "https://api.example.com/oauth/authorize"
|
|
*/
|
|
authorizationUrl?: string;
|
|
|
|
/**
|
|
* The token URL to be used for this flow. This MUST be in the form of a URL.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flow-object | OpenAPI 3.0.4 OAuth Flow Object - tokenUrl} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flow-object | OpenAPI 3.0.3 OAuth Flow Object - tokenUrl} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flow-object | OpenAPI 3.0.2 OAuth Flow Object - tokenUrl} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flow-object | OpenAPI 3.0.1 OAuth Flow Object - tokenUrl} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flow-object | OpenAPI 3.0.0 OAuth Flow Object - tokenUrl} |
|
|
* @property `tokenUrl` - Optional The token URL to be used for this flow
|
|
*
|
|
* @example "https://example.com/oauth/token"
|
|
* @example "https://api.example.com/oauth/token"
|
|
*/
|
|
tokenUrl?: string;
|
|
|
|
/**
|
|
* The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flow-object | OpenAPI 3.0.4 OAuth Flow Object - refreshUrl} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flow-object | OpenAPI 3.0.3 OAuth Flow Object - refreshUrl} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flow-object | OpenAPI 3.0.2 OAuth Flow Object - refreshUrl} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flow-object | OpenAPI 3.0.1 OAuth Flow Object - refreshUrl} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flow-object | OpenAPI 3.0.0 OAuth Flow Object - refreshUrl} |
|
|
* @property `refreshUrl` - Optional The URL to be used for obtaining refresh tokens
|
|
*
|
|
* @example "https://example.com/oauth/refresh"
|
|
* @example "https://api.example.com/oauth/refresh"
|
|
*/
|
|
refreshUrl?: string;
|
|
|
|
/**
|
|
* The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.
|
|
* *
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#oauth-flow-object | OpenAPI 3.0.4 OAuth Flow Object - scopes} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#oauth-flow-object | OpenAPI 3.0.3 OAuth Flow Object - scopes} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#oauth-flow-object | OpenAPI 3.0.2 OAuth Flow Object - scopes} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#oauth-flow-object | OpenAPI 3.0.1 OAuth Flow Object - scopes} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#oauth-flow-object | OpenAPI 3.0.0 OAuth Flow Object - scopes} |
|
|
* @property `scopes` - Required The available scopes for the OAuth2 security scheme
|
|
*
|
|
* @example { "read": "Read access", "write": "Write access" }
|
|
* @example { "admin": "Administrative access" }
|
|
*/
|
|
scopes: Record<string, string>;
|
|
}
|
|
|
|
/**
|
|
* -----
|
|
* Security Requirement Object
|
|
* -----
|
|
*
|
|
* Lists the required security schemes to execute this operation.
|
|
*
|
|
* The Security Requirement Object lists the required security schemes to execute
|
|
* this operation. The name used for each property MUST correspond to a security
|
|
* scheme declared in the Security Schemes under the Components Object.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.0.4 | {@link https://spec.openapis.org/oas/v3.0.4#security-requirement-object | OpenAPI 3.0.4 Security Requirement} |
|
|
* | 3.0.3 | {@link https://spec.openapis.org/oas/v3.0.3#security-requirement-object | OpenAPI 3.0.3 Security Requirement} |
|
|
* | 3.0.2 | {@link https://spec.openapis.org/oas/v3.0.2#security-requirement-object | OpenAPI 3.0.2 Security Requirement} |
|
|
* | 3.0.1 | {@link https://spec.openapis.org/oas/v3.0.1#security-requirement-object | OpenAPI 3.0.1 Security Requirement} |
|
|
* | 3.0.0 | {@link https://spec.openapis.org/oas/v3.0.0#security-requirement-object | OpenAPI 3.0.0 Security Requirement} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @property `{name}` - Each name MUST correspond to a security scheme declared in the Security Schemes
|
|
*
|
|
* @note
|
|
* Security Requirement Objects that contain multiple schemes require that all schemes
|
|
* MUST be satisfied for a request to be authorized. When a list of Security Requirement
|
|
* Objects is defined, only one of the Security Requirement Objects in the list needs to
|
|
* be satisfied to authorize the request.
|
|
*
|
|
* If the security scheme is of type "oauth2" or "openIdConnect", then the value is a list
|
|
* of scope names required for the execution. For other security scheme types, the array
|
|
* MUST be empty.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (API key security):
|
|
* ```ts
|
|
* const requirement: SecurityRequirement = {
|
|
* "api_key": []
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (OAuth2 security with scopes):
|
|
* ```ts
|
|
* const requirement: SecurityRequirement = {
|
|
* "petstore_auth": [
|
|
* "write:pets",
|
|
* "read:pets"
|
|
* ]
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (multiple schemes required):
|
|
* ```ts
|
|
* const requirement: SecurityRequirement = {
|
|
* "api_key": [],
|
|
* "oauth2": ["read", "write"]
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface SecurityRequirement {
|
|
[schemeName: string]: string[];
|
|
}
|