mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-09 20:47:44 +00:00
Add new OpenAPI 2.0 and 3.0 specifications, including comprehensive type definitions and example files. Update .gitignore and bunfig.toml, and remove obsolete MIGRATION.md. Enhance README with additional usage examples and clarify type definitions.
This commit is contained in:
Luke Hagar
366
3.1/security.ts
Normal file
366
3.1/security.ts
Normal file
@@ -0,0 +1,366 @@
|
||||
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
|
||||
* -----
|
||||
*
|
||||
* @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. 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"
|
||||
* }
|
||||
* }
|
||||
* }
|
||||
* };
|
||||
* ```
|
||||
*
|
||||
* @example (Mutual TLS):
|
||||
* ```ts
|
||||
* const securityScheme: SecurityScheme = {
|
||||
* type: "mutualTLS"
|
||||
* };
|
||||
* ```
|
||||
*/
|
||||
export interface SecurityScheme extends Extension {
|
||||
/**
|
||||
* The type of the security scheme. This field is required.
|
||||
*
|
||||
* @example "apiKey"
|
||||
* @example "http"
|
||||
* @example "mutualTLS"
|
||||
* @example "oauth2"
|
||||
* @example "openIdConnect"
|
||||
*/
|
||||
type: "apiKey" | "http" | "mutualTLS" | "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
|
||||
* -----
|
||||
*
|
||||
* @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 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
|
||||
* -----
|
||||
*
|
||||
* @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. 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
|
||||
* -----
|
||||
*
|
||||
* @property `{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[];
|
||||
}
|
||||
Reference in New Issue
Block a user