Add support for security and securitySchemes

[elsmr]

Hi :wave: 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 :smile: 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

[ghost]

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

[ghost]

Would it be possible to simply add the TS definitions per the issue template and https://github.com/drwpow/openapi-typescript/issues/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!!🙏

[github-actions[bot]]

This issue is stale because it has been open for 90 days with no activity. If there is no activity in the next 7 days, the issue will be closed.

[drwpow]

@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.

@radist2s I already said I’d welcome a PR. and it has the label “PRs welcome.” Any time an issue has either of these things no additional permissions are needed to open a PR 😉

[FreeAoi]

@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.

@radist2s I already said I’d welcome a PR. and it has the label “PRs welcome.” Any time an issue has either of these things no additional permissions are needed to open a PR 😉

Hi, I am interested in this PR. What's the goal of this PR and how should it looks like

[drwpow]

@FreeAoi please see the relevant CONTRIBUTING.md guidelines for submitting PRs. PRs are required to have tests. Documentation for this may not be required even though it’s a feature.