Apply openapi3 extension on Security schemes

.chronus/changes/set-openapi3-extension-security-schemes-2024-6-2-17-4-20.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Apply openapi3 extension on Security schemes

.chronus/changes/set-openapi3-extension-security-schemes-2024-6-2-17-7-34.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/http"
+---
+
+Expose `model` property on `HttpAuth` to retrieve original type used to define security scheme

packages/http/src/auth.ts

@@ -10,7 +10,6 @@ import {
   HttpService,
   HttpServiceAuthentication,
   OAuth2Flow,
-  OAuth2Scope,
   Oauth2Auth,
 } from "./types.js";
 
@@ -141,13 +140,12 @@ function mergeOAuthScopes<Flows extends OAuth2Flow[]>(
   };
 }
 
-function setOauth2Scopes<Flows extends OAuth2Flow[]>(
-  scheme: Oauth2Auth<Flows>,
-  scopes: OAuth2Scope[]
-): Oauth2Auth<Flows> {
+function ignoreScopes<Flows extends OAuth2Flow[]>(
+  scheme: Omit<Oauth2Auth<Flows>, "model">
+): Omit<Oauth2Auth<Flows>, "model"> {
   const flows: Flows = deepClone(scheme.flows);
   flows.forEach((flow) => {
-    flow.scopes = scopes;
+    flow.scopes = [];
   });
   return {
     ...scheme,
@@ -156,8 +154,10 @@ function setOauth2Scopes<Flows extends OAuth2Flow[]>(
 }
 
 function authsAreEqual(scheme1: HttpAuth, scheme2: HttpAuth): boolean {
-  if (scheme1.type === "oauth2" && scheme2.type === "oauth2") {
-    return deepEquals(setOauth2Scopes(scheme1, []), setOauth2Scopes(scheme2, []));
+  const { model: _model1, ...withoutModel1 } = scheme1;
+  const { model: _model2, ...withoutModel2 } = scheme2;
+  if (withoutModel1.type === "oauth2" && withoutModel2.type === "oauth2") {
+    return deepEquals(ignoreScopes(withoutModel1), ignoreScopes(withoutModel2));
   }
-  return deepEquals(scheme1, scheme2);
+  return deepEquals(withoutModel1, withoutModel2);
 }

packages/http/src/decorators.ts

@@ -584,7 +584,10 @@ function extractHttpAuthentication(
     return [result, diagnostics];
   }
   const description = getDoc(program, modelType);
-  const auth = result.type === "oauth2" ? extractOAuth2Auth(result) : result;
+  const auth =
+    result.type === "oauth2"
+      ? extractOAuth2Auth(modelType, result)
+      : { ...result, model: modelType };
   return [
     {
       ...auth,
@@ -595,7 +598,7 @@ function extractHttpAuthentication(
   ];
 }
 
-function extractOAuth2Auth(data: any): HttpAuth {
+function extractOAuth2Auth(modelType: Model, data: any): HttpAuth {
   // Validation of OAuth2Flow models in this function is minimal because the
   // type system already validates whether the model represents a flow
   // configuration.  This code merely avoids runtime errors.
@@ -608,6 +611,7 @@ function extractOAuth2Auth(data: any): HttpAuth {
   return {
     id: data.id,
     type: data.type,
+    model: modelType,
     flows: flows.map((flow: any) => {
       const scopes: Array<string> = flow.scopes ? flow.scopes : defaultScopes;
       return {

packages/http/src/types.ts

@@ -55,6 +55,9 @@ export interface HttpAuthBase {
    * Optional description.
    */
   description?: string;
+
+  /** Model that defined the authentication */
+  readonly model: Model;
 }
 
 /**

packages/http/test/http-decorators.test.ts

@@ -5,7 +5,7 @@ import {
   expectDiagnostics,
 } from "@typespec/compiler/testing";
 import { deepStrictEqual, ok, strictEqual } from "assert";
-import { beforeEach, describe, it } from "vitest";
+import { beforeEach, describe, expect, it } from "vitest";
 import {
   getAuthentication,
   getHeaderFieldName,
@@ -726,14 +726,15 @@ describe("http: decorators", () => {
         @test namespace Foo {}
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo), {
+      expect(getAuthentication(runner.program, Foo)).toEqual({
         options: [
           {
             schemes: [
               {
                 id: "BasicAuth",
                 type: "http",
                 scheme: "basic",
+                model: expect.objectContaining({ kind: "Model" }),
               },
             ],
           },
@@ -749,11 +750,17 @@ describe("http: decorators", () => {
         @test namespace Foo {}
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo), {
+      expect(getAuthentication(runner.program, Foo)).toEqual({
         options: [
           {
             schemes: [
-              { id: "MyAuth", description: "My custom basic auth", type: "http", scheme: "basic" },
+              {
+                id: "MyAuth",
+                description: "My custom basic auth",
+                type: "http",
+                scheme: "basic",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
             ],
           },
         ],
@@ -766,14 +773,15 @@ describe("http: decorators", () => {
         @test namespace Foo {}
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo), {
+      expect(getAuthentication(runner.program, Foo)).toEqual({
         options: [
           {
             schemes: [
               {
                 id: "BearerAuth",
                 type: "http",
                 scheme: "bearer",
+                model: expect.objectContaining({ kind: "Model" }),
               },
             ],
           },
@@ -787,7 +795,7 @@ describe("http: decorators", () => {
         @test namespace Foo {}
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo), {
+      expect(getAuthentication(runner.program, Foo)).toEqual({
         options: [
           {
             schemes: [
@@ -796,6 +804,7 @@ describe("http: decorators", () => {
                 type: "apiKey",
                 in: "header",
                 name: "x-my-header",
+                model: expect.objectContaining({ kind: "Model" }),
               },
             ],
           },
@@ -815,7 +824,7 @@ describe("http: decorators", () => {
         @test namespace Foo {}
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo), {
+      expect(getAuthentication(runner.program, Foo)).toEqual({
         options: [
           {
             schemes: [
@@ -830,6 +839,7 @@ describe("http: decorators", () => {
                     scopes: [{ value: "read" }, { value: "write" }],
                   },
                 ],
+                model: expect.objectContaining({ kind: "Model" }),
               },
             ],
           },
@@ -849,7 +859,7 @@ describe("http: decorators", () => {
         @test namespace Foo {}
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo), {
+      expect(getAuthentication(runner.program, Foo)).toEqual({
         options: [
           {
             schemes: [
@@ -864,6 +874,7 @@ describe("http: decorators", () => {
                     scopes: [{ value: "read" }, { value: "write" }],
                   },
                 ],
+                model: expect.objectContaining({ kind: "Model" }),
               },
             ],
           },
@@ -877,13 +888,14 @@ describe("http: decorators", () => {
         @test namespace Foo {}
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo), {
+      expect(getAuthentication(runner.program, Foo)).toEqual({
         options: [
           {
             schemes: [
               {
                 id: "NoAuth",
                 type: "noAuth",
+                model: expect.objectContaining({ kind: "Model" }),
               },
             ],
           },
@@ -897,13 +909,27 @@ describe("http: decorators", () => {
         @test namespace Foo {}
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo), {
+      expect(getAuthentication(runner.program, Foo)).toEqual({
         options: [
           {
-            schemes: [{ id: "BasicAuth", type: "http", scheme: "basic" }],
+            schemes: [
+              {
+                id: "BasicAuth",
+                type: "http",
+                scheme: "basic",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
+            ],
           },
           {
-            schemes: [{ id: "BearerAuth", type: "http", scheme: "bearer" }],
+            schemes: [
+              {
+                id: "BearerAuth",
+                type: "http",
+                scheme: "bearer",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
+            ],
           },
         ],
       });
@@ -915,12 +941,22 @@ describe("http: decorators", () => {
         @test namespace Foo {}
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo), {
+      expect(getAuthentication(runner.program, Foo)).toEqual({
         options: [
           {
             schemes: [
-              { id: "BasicAuth", type: "http", scheme: "basic" },
-              { id: "BearerAuth", type: "http", scheme: "bearer" },
+              {
+                id: "BasicAuth",
+                type: "http",
+                scheme: "basic",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
+              {
+                id: "BearerAuth",
+                type: "http",
+                scheme: "bearer",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
             ],
           },
         ],
@@ -933,10 +969,17 @@ describe("http: decorators", () => {
         @test namespace Foo {}
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo), {
+      expect(getAuthentication(runner.program, Foo)).toEqual({
         options: [
           {
-            schemes: [{ id: "BearerAuth", type: "http", scheme: "bearer" }],
+            schemes: [
+              {
+                id: "BearerAuth",
+                type: "http",
+                scheme: "bearer",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
+            ],
           },
           {
             schemes: [
@@ -945,8 +988,14 @@ describe("http: decorators", () => {
                 type: "apiKey",
                 in: "header",
                 name: "x-my-header",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
+              {
+                id: "BasicAuth",
+                type: "http",
+                scheme: "basic",
+                model: expect.objectContaining({ kind: "Model" }),
               },
-              { id: "BasicAuth", type: "http", scheme: "basic" },
             ],
           },
         ],
@@ -963,13 +1012,27 @@ describe("http: decorators", () => {
         }
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo.interfaces.get("Bar")!), {
+      expect(getAuthentication(runner.program, Foo.interfaces.get("Bar")!)).toEqual({
         options: [
           {
-            schemes: [{ id: "BasicAuth", type: "http", scheme: "basic" }],
+            schemes: [
+              {
+                id: "BasicAuth",
+                type: "http",
+                scheme: "basic",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
+            ],
           },
           {
-            schemes: [{ id: "BearerAuth", type: "http", scheme: "bearer" }],
+            schemes: [
+              {
+                id: "BearerAuth",
+                type: "http",
+                scheme: "bearer",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
+            ],
           },
         ],
       });
@@ -985,12 +1048,22 @@ describe("http: decorators", () => {
         }
       `)) as { Foo: Namespace };
 
-      deepStrictEqual(getAuthentication(runner.program, Foo.operations.get("bar")!), {
+      expect(getAuthentication(runner.program, Foo.operations.get("bar")!)).toEqual({
         options: [
           {
             schemes: [
-              { id: "BasicAuth", type: "http", scheme: "basic" },
-              { id: "BearerAuth", type: "http", scheme: "bearer" },
+              {
+                id: "BasicAuth",
+                type: "http",
+                scheme: "basic",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
+              {
+                id: "BearerAuth",
+                type: "http",
+                scheme: "bearer",
+                model: expect.objectContaining({ kind: "Model" }),
+              },
             ],
           },
         ],

packages/openapi3/src/openapi.ts

@@ -1816,6 +1816,14 @@ function createOAPIEmitter(
   }
 
   function getOpenAPI3Scheme(auth: HttpAuth): OpenAPI3SecurityScheme | undefined {
+    const scheme = getOpenAPI3SchemeInternal(auth);
+
+    if (scheme) {
+      attachExtensions(program, auth.model, scheme);
+    }
+    return scheme;
+  }
+  function getOpenAPI3SchemeInternal(auth: HttpAuth): OpenAPI3SecurityScheme | undefined {
     switch (auth.type) {
       case "http":
         return { type: "http", scheme: auth.scheme, description: auth.description };