Add support for security and securitySchemes

[elsmr]

Hi 👋 I need to generate types for components.securitySchemes, and security on each operation.

Is this something that would be useful for this library, or is it out of scope?

I already starting working on this in my fork. If it would be useful to this library, I would like to contribute 😄 let me know!

Example

securityScheme definition:

components:
  securitySchemes:
      Bearer:
        type: 'http'
        scheme: 'bearer'

Usage on operation (or global)

security:
  - Bearer: []

More context: https://swagger.io/docs/specification/authentication

Has anyone given any thought to how this could be approached, as it would be really useful for a use case we have.

In summary, our use case, is that I want to programatically understand what security scheme are either applied globally or at the operation level, in order to control security validation via a single reference source rather than having separately defined the security controls in the Open API Schema and Application Code

[drwpow]

There have been some other requests for 3.1 features such as this. If anyone has a recommendation as to how it could be implemented in TypeScript, please share!

[drwpow]

So I took a look at this, and it wasn’t clear to me how TypeScript types could be generated from these. As far as I could tell, these are just values for you to analyze at runtime, but I’m not sure if it’s necessary to generate schemas for a limited format.

I’d be willing to add it if someone could provide an example with:

1. An example OpenAPI schema
2. The generated types
3. How one might use these types

Would it be possible to simply add the TS definitions per the issue template and #939? I think support for the code generation portion could be handled separately. I'm currently using a local workaround below; I'm sure it could be made slightly more complex to cover the conditional use cases between apiKey and http and the other schemes.

declare module 'openapi-typescript' {
	/**
	 * Not in scope at this time, but could be included with more specificity for OAuth support.
	 * https://swagger.io/specification/#oauth-flows-object
	 */
	export type OAuthFlowsObject = any;

	/**
	 * https://swagger.io/specification/#security-requirement-object
	 */
	export interface SecurityRequirementObject {
		/**
		 * Each name MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object. If the security scheme is of type "oauth2" or "openIdConnect", then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MUST be empty.
		 */
		[name: string]: string[];
	}

	/**
	 * https://swagger.io/specification/#security-scheme-object
	 */
	export interface SecuritySchemesObject {
		[securityScheme: string]: {
			/**
			 * REQUIRED.
			 * Applies To: ANY.
			 * The type of the security scheme. Valid values are "apiKey", "http", "oauth2", "openIdConnect".
			 */
			type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
			/**
			 * Applies To: ANY.
			 * A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
			 */
			description?: string;
			/**
			 * REQUIRED.
			 * Applies To: apiKey.
			 * The name of the header, query or cookie parameter to be used.
			 */
			name?: string;
			/**
			 * REQUIRED.
			 * Applies To: apiKey.
			 * The location of the API key. Valid values are "query", "header" or "cookie".
			 */
			in?: 'query' | 'header' | 'cookie';
			/**
			 * REQUIRED.
			 * Applies To: http.
			 * The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235. The values used SHOULD be registered in the IANA Authentication Scheme registry.
			 */
			scheme?: string;
			/**
			 * Applies To: http("bearer")
			 * 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.
			 */
			bearerFormat?: string;
			/**
			 * REQUIRED.
			 * Applies To: oauth2.
			 * An object containing configuration information for the flow types supported.
			 */
			flows?: OAuthFlowsObject;
			/**
			 * REQUIRED.
			 * Applies To: openIdConnect.
			 * OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.
			 */
			openIdConnectUrl?: string;
		};
	}

	export interface OperationObject {
		security?: SecurityRequirementObject[];
	}

	export interface OpenAPI3 {
		security?: SecurityRequirementObject[];
		securitySchemes?: SecuritySchemesObject;
	}
}

[drwpow]

Oh, like, just ship a generic, static type? 🤔 Yeah that could work!

I’d be open to a PR if someone can make one 🙏

[radist2s]

@drwpow, I need the securitySchemes types as well. I was wondering if you are currently implementing this functionality? If not, I would try to do a PR.

[derodero24]

@radist2s please!!🙏