Update service authentication OAuth2 flow scopes to be object with description.

common/changes/@cadl-lang/openapi3/update-for-swagger-linter_2022-08-11-21-09.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@cadl-lang/openapi3",
+      "comment": "Uptake changes to http service authentication oauth2 scopes",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@cadl-lang/openapi3"
+}

common/changes/@cadl-lang/rest/update-for-swagger-linter_2022-08-11-21-09.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@cadl-lang/rest",
+      "comment": "Api: Service Authentication oauth2 flow scopes is now an object with value and description",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@cadl-lang/rest"
+}

packages/openapi3/src/openapi.ts

@@ -1360,12 +1360,12 @@ function createOAPIEmitter(program: Program, options: ResolvedOpenAPI3EmitterOpt
         const flows: OpenAPI3OAuthFlows = {};
         const scopes: string[] = [];
         for (const flow of auth.flows) {
-          scopes.push(...flow.scopes);
+          scopes.push(...flow.scopes.map((x) => x.value));
           flows[flow.type] = {
             authorizationUrl: (flow as any).authorizationUrl,
             tokenUrl: (flow as any).tokenUrl,
             refreshUrl: flow.refreshUrl,
-            scopes: Object.fromEntries(flow.scopes.map((x: string) => [x, ""])),
+            scopes: Object.fromEntries(flow.scopes.map((x) => [x.value, x.description ?? ""])),
           };
         }
         return [{ type: "oauth2", flows, description: auth.description }, scopes];

packages/rest/src/http/decorators.ts

@@ -517,16 +517,29 @@ function extractHttpAuthentication(
     return [result, diagnostics];
   }
   const description = getDoc(program, modelType);
+  const auth = result.type === "oauth2" ? extractOAuth2Auth(result) : result;
   return [
     {
-      ...result,
+      ...auth,
       id: modelType.name || result.type,
       ...(description && { description }),
     },
     diagnostics,
   ];
 }
 
+function extractOAuth2Auth(data: any): HttpAuth {
+  return {
+    ...data,
+    flows: data.flows.map((flow: any) => {
+      return {
+        ...flow,
+        scopes: flow.scopes.map((x: string) => ({ value: x })),
+      };
+    }),
+  };
+}
+
 export function getAuthentication(
   program: Program,
   namespace: Namespace

packages/rest/src/http/types.ts

@@ -112,7 +112,7 @@ export interface AuthorizationCodeFlow {
   authorizationUrl: string;
   tokenUrl: string;
   refreshUrl?: string;
-  scopes: string[];
+  scopes: OAuth2Scope[];
 }
 
 /**
@@ -122,7 +122,7 @@ export interface ImplicitFlow {
   type: "implicit";
   authorizationUrl: string;
   refreshUrl?: string;
-  scopes: string[];
+  scopes: OAuth2Scope[];
 }
 
 /**
@@ -132,7 +132,7 @@ export interface PasswordFlow {
   type: "password";
   authorizationUrl: string;
   refreshUrl?: string;
-  scopes: string[];
+  scopes: OAuth2Scope[];
 }
 
 /**
@@ -142,5 +142,10 @@ export interface ClientCredentialsFlow {
   type: "clientCredentials";
   tokenUrl: string;
   refreshUrl?: string;
-  scopes: string[];
+  scopes: OAuth2Scope[];
+}
+
+export interface OAuth2Scope {
+  value: string;
+  description?: string;
 }

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

@@ -493,7 +493,7 @@ describe("rest: http decorators", () => {
                     type: "implicit",
                     authorizationUrl: "https://api.example.com/oauth2/authorize",
                     refreshUrl: "https://api.example.com/oauth2/refresh",
-                    scopes: ["read", "write"],
+                    scopes: [{ value: "read" }, { value: "write" }],
                   },
                 ],
               },