feat: display security scheme roles (#2599)

* feat: display security scheme roles * feat: upgrade http-spec to the newest version
stoplightio · Jun 19, 2024 · 7937f70 · 7937f70
1 parent e0b10da
commit 7937f70
Show file tree

Hide file tree

Showing 6 changed files with 96 additions and 27 deletions.
diff --git a/packages/elements-core/package.json b/packages/elements-core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stoplight/elements-core",
-  "version": "8.3.1",
+  "version": "8.3.2",
   "sideEffects": [
     "web-components.min.js",
     "src/web-components/**",
@@ -57,7 +57,7 @@
     ]
   },
   "dependencies": {
-    "@stoplight/http-spec": "^7.0.3",
+    "@stoplight/http-spec": "^7.1.0",
     "@stoplight/json": "^3.21.0",
     "@stoplight/json-schema-ref-parser": "^9.2.7",
     "@stoplight/json-schema-sampler": "0.3.0",

diff --git a/packages/elements-core/src/utils/__tests__/securitySchemes.spec.ts b/packages/elements-core/src/utils/__tests__/securitySchemes.spec.ts
@@ -106,4 +106,32 @@ describe('getDefaultDescription()', () => {
       - \`scope:password\` - password scope description"
     `);
   });
+
+  it('should handle api key flow with roles', () => {
+    const description = getDefaultDescription({
+      id: 'security-apikey-access-token',
+      key: 'apikey-access-token',
+      type: 'apiKey',
+      name: 'access_token',
+      in: 'query',
+      extensions: { ['x-scopes']: ['image:read', 'user:read'] },
+    });
+
+    expect(description).toContain('Roles: `image:read`, `user:read`');
+  });
+
+  it.each<'bearer' | 'basic' | 'digest'>(['bearer', 'basic', 'digest'])(
+    'should handle http %s flow with roles',
+    scheme => {
+      const description = getDefaultDescription({
+        id: 'security-http-access-token',
+        key: 'http-access-token',
+        type: 'http',
+        scheme,
+        extensions: { ['x-scopes']: ['image:read', 'user:read'] },
+      });
+
+      expect(description).toContain('Roles: `image:read`, `user:read`');
+    },
+  );
 });
diff --git a/packages/elements-core/src/utils/securitySchemes.ts b/packages/elements-core/src/utils/securitySchemes.ts
@@ -1,4 +1,12 @@
-import { HttpSecurityScheme, IOauth2Flow, IOauth2SecurityScheme, IOauthFlowObjects } from '@stoplight/types';
+import {
+  HttpSecurityScheme,
+  IApiKeySecurityScheme,
+  IBasicSecurityScheme,
+  IBearerSecurityScheme,
+  IOauth2Flow,
+  IOauth2SecurityScheme,
+  IOauthFlowObjects,
+} from '@stoplight/types';
 import { entries, keys } from 'lodash';
 
 import {
@@ -17,15 +25,15 @@ const oauthFlowNames: Record<keyof IOauthFlowObjects, string> = {
 export function getDefaultDescription(scheme: HttpSecurityScheme) {
   switch (scheme.type) {
     case 'apiKey':
-      return getApiKeyDescription(scheme.in, scheme.name);
+      return getApiKeyDescription(scheme);
     case 'http':
       switch (scheme.scheme) {
         case 'basic':
-          return getBasicAuthDescription();
+          return getBasicAuthDescription(scheme);
         case 'bearer':
-          return getBearerAuthDescription();
+          return getBearerAuthDescription(scheme);
         case 'digest':
-          return getDigestAuthDescription();
+          return getDigestAuthDescription(scheme);
       }
     case 'oauth2':
       return getOAuthDescription(scheme);
@@ -38,30 +46,33 @@ export function getOptionalAuthDescription() {
   return `Providing Auth is optional; requests may be made without an included Authorization header.`;
 }
 
-function getApiKeyDescription(inProperty: 'header' | 'cookie' | 'query', name: string) {
+function getApiKeyDescription(scheme: IApiKeySecurityScheme) {
+  const { in: inProperty, name } = scheme;
   return `An API key is a token that you provide when making API calls. Include the token in a ${inProperty} parameter called \`${name}\`.
 
-  Example: ${inProperty === 'query' ? `\`?${name}=123\`` : `\`${name}: 123\``}`;
+  Example: ${inProperty === 'query' ? `\`?${name}=123\`` : `\`${name}: 123\``}${getSecuritySchemeRoles(scheme)}`;
 }
 
-function getBasicAuthDescription() {
+function getBasicAuthDescription(schema: IBasicSecurityScheme) {
   return `Basic authentication is a simple authentication scheme built into the HTTP protocol.
   To use it, send your HTTP requests with an Authorization header that contains the word Basic
   followed by a space and a base64-encoded string \`username:password\`.
 
-  Example: \`Authorization: Basic ZGVtbzpwQDU1dzByZA==\``;
+  Example: \`Authorization: Basic ZGVtbzpwQDU1dzByZA==\`${getSecuritySchemeRoles(schema)}`;
 }
 
-function getBearerAuthDescription() {
+function getBearerAuthDescription(schema: IBearerSecurityScheme) {
   return `Provide your bearer token in the Authorization header when making requests to protected resources.
 
-  Example: \`Authorization: Bearer 123\``;
+  Example: \`Authorization: Bearer 123\`${getSecuritySchemeRoles(schema)}`;
 }
 
-function getDigestAuthDescription() {
+function getDigestAuthDescription(schema: IBasicSecurityScheme) {
   return `Provide your encrypted digest scheme data in the Authorization header when making requests to protected resources.
 
-  Example: \`Authorization: Digest username=guest, realm="test", nonce="2", uri="/uri", response="123"\``;
+  Example: \`Authorization: Digest username=guest, realm="test", nonce="2", uri="/uri", response="123"\`${getSecuritySchemeRoles(
+    schema,
+  )}`;
 }
 
 function getOAuthDescription(scheme: IOauth2SecurityScheme) {
@@ -92,3 +103,8 @@ ${scopes.map(([key, value]) => `- \`${key}\` - ${value}`).join('\n')}`;
 
   return description;
 }
+
+function getSecuritySchemeRoles(scheme: HttpSecurityScheme) {
+  const scopes = scheme.extensions?.['x-scopes'];
+  return Array.isArray(scopes) ? `\n\nRoles: ${scopes.map(scope => `\`${scope}\``).join(', ')}` : '';
+}
diff --git a/packages/elements-dev-portal/package.json b/packages/elements-dev-portal/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stoplight/elements-dev-portal",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "description": "UI components for composing beautiful developer documentation.",
   "keywords": [],
   "sideEffects": [
@@ -64,7 +64,7 @@
     ]
   },
   "dependencies": {
-    "@stoplight/elements-core": "~8.3.1",
+    "@stoplight/elements-core": "~8.3.2",
     "@stoplight/markdown-viewer": "^5.7.0",
     "@stoplight/mosaic": "^1.53.1",
     "@stoplight/path": "^1.3.2",

diff --git a/packages/elements/package.json b/packages/elements/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@stoplight/elements",
-  "version": "8.3.1",
+  "version": "8.3.2",
   "description": "UI components for composing beautiful developer documentation.",
   "keywords": [],
   "sideEffects": [
@@ -63,8 +63,8 @@
     ]
   },
   "dependencies": {
-    "@stoplight/elements-core": "~8.3.1",
-    "@stoplight/http-spec": "^7.0.3",
+    "@stoplight/elements-core": "~8.3.2",
+    "@stoplight/http-spec": "^7.1.0",
     "@stoplight/json": "^3.18.1",
     "@stoplight/mosaic": "^1.53.1",
     "@stoplight/types": "^14.1.1",

diff --git a/yarn.lock b/yarn.lock
@@ -3906,10 +3906,10 @@
   dependencies:
     eslint-config-prettier "^8.3.0"
 
-"@stoplight/http-spec@^7.0.3":
-  version "7.0.3"
-  resolved "https://registry.yarnpkg.com/@stoplight/http-spec/-/http-spec-7.0.3.tgz#a27a3a72d429114e7994512f435312b5ee448c8b"
-  integrity sha512-r9Y8rT4RbqY7NWqSXjiqtBq0Nme2K5cArSX9gDPeuud8F4CwbizP7xkUwLdwDdHgoJkyIQ3vkFJpHzUVCQeOOA==
+"@stoplight/http-spec@^7.1.0":
+  version "7.1.0"
+  resolved "https://registry.yarnpkg.com/@stoplight/http-spec/-/http-spec-7.1.0.tgz#516fec5f4b08cc93dadfb4969a6f9616165b0553"
+  integrity sha512-Z2XqKX2SV8a1rrgSzFqccX2TolfcblT+l4pNvUU+THaLl50tKDoeidwWWZTzYUzqU0+UV97ponvqEbWWN3PaXg==
   dependencies:
     "@stoplight/json" "^3.18.1"
     "@stoplight/json-schema-generator" "1.0.2"
@@ -18841,7 +18841,7 @@ string-length@^4.0.1:
     char-regex "^1.0.2"
     strip-ansi "^6.0.0"
 
-"string-width-cjs@npm:string-width@^4.2.0", "string-width@^1.0.2 || 2 || 3 || 4", string-width@^4.0.0, string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3:
+"string-width-cjs@npm:string-width@^4.2.0":
   version "4.2.3"
   resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
   integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==
@@ -18859,6 +18859,15 @@ string-width@^1.0.1:
     is-fullwidth-code-point "^1.0.0"
     strip-ansi "^3.0.0"
 
+"string-width@^1.0.2 || 2 || 3 || 4", string-width@^4.0.0, string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3:
+  version "4.2.3"
+  resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
+  integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==
+  dependencies:
+    emoji-regex "^8.0.0"
+    is-fullwidth-code-point "^3.0.0"
+    strip-ansi "^6.0.1"
+
 string-width@^2.1.1:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/string-width/-/string-width-2.1.1.tgz#ab93f27a8dc13d28cac815c462143a6d9012ae9e"
@@ -18947,7 +18956,7 @@ [email protected], stringify-object@^3.3.0:
     is-obj "^1.0.1"
     is-regexp "^1.0.0"
 
-"strip-ansi-cjs@npm:strip-ansi@^6.0.1", strip-ansi@^6.0.0, strip-ansi@^6.0.1:
+"strip-ansi-cjs@npm:strip-ansi@^6.0.1":
   version "6.0.1"
   resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9"
   integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==
@@ -18975,6 +18984,13 @@ strip-ansi@^5.0.0, strip-ansi@^5.1.0, strip-ansi@^5.2.0:
   dependencies:
     ansi-regex "^4.1.0"
 
+strip-ansi@^6.0.0, strip-ansi@^6.0.1:
+  version "6.0.1"
+  resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9"
+  integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==
+  dependencies:
+    ansi-regex "^5.0.1"
+
 strip-ansi@^7.0.1:
   version "7.1.0"
   resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-7.1.0.tgz#d5b6568ca689d8561370b0707685d22434faff45"
@@ -20700,7 +20716,7 @@ wordwrap@^1.0.0:
   resolved "https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb"
   integrity sha1-J1hIEIkUVqQXHI0CJkQa3pDLyus=
 
-"wrap-ansi-cjs@npm:wrap-ansi@^7.0.0", wrap-ansi@^7.0.0:
+"wrap-ansi-cjs@npm:wrap-ansi@^7.0.0":
   version "7.0.0"
   resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43"
   integrity sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==
@@ -20735,6 +20751,15 @@ wrap-ansi@^6.0.1, wrap-ansi@^6.2.0:
     string-width "^4.1.0"
     strip-ansi "^6.0.0"
 
+wrap-ansi@^7.0.0:
+  version "7.0.0"
+  resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43"
+  integrity sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==
+  dependencies:
+    ansi-styles "^4.0.0"
+    string-width "^4.1.0"
+    strip-ansi "^6.0.0"
+
 wrap-ansi@^8.1.0:
   version "8.1.0"
   resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-8.1.0.tgz#56dc22368ee570face1b49819975d9b9a5ead214"