mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 04:20:29 +00:00
359 lines
10 KiB
TypeScript
359 lines
10 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, a cookie parameter or
|
|
* as a query parameter), mutual TLS (use of a client certificate), OAuth2's common
|
|
* flows (implicit, password, client credentials and authorization code) as defined
|
|
* in RFC6749, and OpenID Connect Discovery.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#security-scheme-object | OpenAPI 3.1.1 Security Scheme Object} |
|
|
* | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#security-scheme-object | OpenAPI 3.1.0 Security Scheme Object} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @key `type` - Required The type of the security scheme
|
|
* @key `description` - Optional A short description for security scheme
|
|
* @key `name` - Optional The name of the header, query or cookie parameter to be used
|
|
* @key `in` - Optional The location of the API key
|
|
* @key `scheme` - Optional The name of the HTTP Authorization scheme to be used in the Authorization header
|
|
* @key `bearerFormat` - Optional A hint to the client to identify how the bearer token is formatted
|
|
* @key `flows` - Optional An object containing configuration information for the flow types supported
|
|
* @key `openIdConnectUrl` - Optional OpenId Connect URL to discover OAuth2 configuration values
|
|
* @key `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* The `type` field is required. Other fields depend on the security scheme type.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (API Key):
|
|
* ```ts
|
|
* const securityScheme: SecurityScheme = {
|
|
* type: "apiKey",
|
|
* name: "X-API-Key",
|
|
* in: "header"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (HTTP Basic):
|
|
* ```ts
|
|
* const securityScheme: SecurityScheme = {
|
|
* type: "http",
|
|
* scheme: "basic"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (OAuth2):
|
|
* ```ts
|
|
* const securityScheme: SecurityScheme = {
|
|
* type: "oauth2",
|
|
* flows: {
|
|
* authorizationCode: {
|
|
* authorizationUrl: "https://example.com/oauth/authorize",
|
|
* tokenUrl: "https://example.com/oauth/token",
|
|
* scopes: {
|
|
* "read:pets": "read your pets",
|
|
* "write:pets": "modify pets in your account"
|
|
* }
|
|
* }
|
|
* }
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface SecurityScheme extends Extension {
|
|
/**
|
|
* The type of the security scheme. This field is required.
|
|
*
|
|
* @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.
|
|
*
|
|
* @example "API key authentication"
|
|
* @example "OAuth2 authentication with authorization code flow"
|
|
*/
|
|
description?: string
|
|
|
|
/**
|
|
* The name of the header, query or cookie parameter to be used. This field
|
|
* is required for `apiKey` type.
|
|
*
|
|
* @example "X-API-Key"
|
|
* @example "api_key"
|
|
* @example "sessionId"
|
|
*/
|
|
name?: string
|
|
|
|
/**
|
|
* The location of the API key. This field is required for `apiKey` type.
|
|
*
|
|
* @example "header"
|
|
* @example "query"
|
|
* @example "cookie"
|
|
*/
|
|
in?: "query" | "header" | "cookie"
|
|
|
|
/**
|
|
* The name of the HTTP Authorization scheme to be used in the Authorization
|
|
* header. This field is required for `http` type.
|
|
*
|
|
* @example "basic"
|
|
* @example "bearer"
|
|
* @example "digest"
|
|
*/
|
|
scheme?: string
|
|
|
|
/**
|
|
* A hint to the client to identify how the bearer token is formatted. Bearer
|
|
* tokens are usually generated by an authorization server, so this information
|
|
* is primarily for documentation purposes.
|
|
*
|
|
* @example "JWT"
|
|
* @example "Bearer"
|
|
*/
|
|
bearerFormat?: string
|
|
|
|
/**
|
|
* An object containing configuration information for the flow types supported.
|
|
* This field is required for `oauth2` type.
|
|
*
|
|
* @example { authorizationCode: { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token" } }
|
|
*/
|
|
flows?: OAuthFlows
|
|
|
|
/**
|
|
* OpenId Connect URL to discover OAuth2 configuration values. This MUST be
|
|
* in the form of a URL. This field is required for `openIdConnect` type.
|
|
*
|
|
* @example "https://example.com/.well-known/openid_configuration"
|
|
*/
|
|
openIdConnectUrl?: string
|
|
}
|
|
|
|
/**
|
|
* -----
|
|
* OAuth Flows Object
|
|
* -----
|
|
*
|
|
* Allows configuration of the supported OAuth Flows.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#oauth-flows-object | OpenAPI 3.1.1 OAuth Flows Object} |
|
|
* | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#oauth-flows-object | OpenAPI 3.1.0 OAuth Flows Object} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @key `implicit` - Optional Configuration for the OAuth Implicit flow
|
|
* @key `password` - Optional Configuration for the OAuth Resource Owner Password flow
|
|
* @key `clientCredentials` - Optional Configuration for the OAuth Client Credentials flow
|
|
* @key `authorizationCode` - Optional Configuration for the OAuth Authorization Code flow
|
|
* @key `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* All fields are optional. At least one flow must be specified.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (authorization code flow):
|
|
* ```ts
|
|
* const oauthFlows: OAuthFlows = {
|
|
* authorizationCode: {
|
|
* authorizationUrl: "https://example.com/oauth/authorize",
|
|
* tokenUrl: "https://example.com/oauth/token",
|
|
* scopes: {
|
|
* "read:pets": "read your pets",
|
|
* "write:pets": "modify pets in your account"
|
|
* }
|
|
* }
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface OAuthFlows extends Extension {
|
|
/**
|
|
* Configuration for the OAuth Implicit flow.
|
|
*
|
|
* @example { authorizationUrl: "https://example.com/oauth/authorize", scopes: { "read:pets": "read your pets" } }
|
|
*/
|
|
implicit?: OAuthFlow
|
|
|
|
/**
|
|
* Configuration for the OAuth Resource Owner Password flow.
|
|
*
|
|
* @example { tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } }
|
|
*/
|
|
password?: OAuthFlow
|
|
|
|
/**
|
|
* Configuration for the OAuth Client Credentials flow.
|
|
*
|
|
* @example { tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } }
|
|
*/
|
|
clientCredentials?: OAuthFlow
|
|
|
|
/**
|
|
* Configuration for the OAuth Authorization Code flow.
|
|
*
|
|
* @example { authorizationUrl: "https://example.com/oauth/authorize", tokenUrl: "https://example.com/oauth/token", scopes: { "read:pets": "read your pets" } }
|
|
*/
|
|
authorizationCode?: OAuthFlow
|
|
}
|
|
|
|
/**
|
|
* -----
|
|
* OAuth Flow Object
|
|
* -----
|
|
*
|
|
* Configuration details for a supported OAuth Flow.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 3.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#oauth-flow-object | OpenAPI 3.1.1 OAuth Flow Object} |
|
|
* | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#oauth-flow-object | OpenAPI 3.1.0 OAuth Flow Object} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @key `authorizationUrl` - Optional The authorization URL to be used for this flow
|
|
* @key `tokenUrl` - Optional The token URL to be used for this flow
|
|
* @key `refreshUrl` - Optional The URL to be used for obtaining refresh tokens
|
|
* @key `scopes` - Required The available scopes for the OAuth2 security scheme
|
|
* @key `x-${string}` - Specification Extensions
|
|
*
|
|
* @note
|
|
* The `scopes` field is required. Other fields depend on the flow type.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (authorization code flow):
|
|
* ```ts
|
|
* const oauthFlow: OAuthFlow = {
|
|
* authorizationUrl: "https://example.com/oauth/authorize",
|
|
* tokenUrl: "https://example.com/oauth/token",
|
|
* scopes: {
|
|
* "read:pets": "read your pets",
|
|
* "write:pets": "modify pets in your account"
|
|
* }
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface OAuthFlow extends Extension {
|
|
/**
|
|
* The authorization URL to be used for this flow. This MUST be in the form of a URL.
|
|
* This field is required for `implicit` and `authorizationCode` flows.
|
|
*
|
|
* @example "https://example.com/oauth/authorize"
|
|
*/
|
|
authorizationUrl?: string
|
|
|
|
/**
|
|
* The token URL to be used for this flow. This MUST be in the form of a URL.
|
|
* This field is required for `password`, `clientCredentials`, and `authorizationCode` flows.
|
|
*
|
|
* @example "https://example.com/oauth/token"
|
|
*/
|
|
tokenUrl?: string
|
|
|
|
/**
|
|
* The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
|
|
*
|
|
* @example "https://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. This field is required.
|
|
*
|
|
* @example { "read:pets": "read your pets", "write:pets": "modify pets in your account" }
|
|
*/
|
|
scopes: Record<string, string>
|
|
}
|
|
|
|
/**
|
|
* -----
|
|
* Security Requirement Object
|
|
* -----
|
|
*
|
|
* Lists the required security schemes for execution of the 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.1.1 | {@link https://spec.openapis.org/oas/v3.1.1#security-requirement-object | OpenAPI 3.1.1 Security Requirement Object} |
|
|
* | 3.1.0 | {@link https://spec.openapis.org/oas/v3.1.0#security-requirement-object | OpenAPI 3.1.0 Security Requirement Object} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @key `{name}` - Each name MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object
|
|
*
|
|
* @note
|
|
* The property names correspond to security scheme names. The values are arrays of scope names.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (API key):
|
|
* ```ts
|
|
* const securityRequirement: SecurityRequirement = {
|
|
* "api_key": []
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (OAuth2):
|
|
* ```ts
|
|
* const securityRequirement: SecurityRequirement = {
|
|
* "petstore_auth": ["write:pets", "read:pets"]
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (multiple schemes):
|
|
* ```ts
|
|
* const securityRequirement: SecurityRequirement = {
|
|
* "api_key": [],
|
|
* "petstore_auth": ["write:pets", "read:pets"]
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface SecurityRequirement {
|
|
/**
|
|
* Each name MUST correspond to a security scheme which is declared in the
|
|
* Security Schemes under the Components Object. The value is an array of
|
|
* scope names required for the execution. For OAuth2, the scopes are the
|
|
* scopes required for the execution. For other security schemes, the array
|
|
* MUST be empty.
|
|
*
|
|
* @example []
|
|
* @example ["write:pets", "read:pets"]
|
|
*/
|
|
[name: string]: string[]
|
|
}
|