Allow for scope descriptions

[steverice]

This makes a small change to the code introduced in #849 to allow for models to be used as OAuth scopes. Without this check, an object like {value: "foo", description: "bar"} gets wrapped in an additional value key. When the OpenAPI3 emitter tries to print out the securitySchemes, it sees {value: {...}} and produces a scope with value [object Object] and no description.

This also introduces a base SecurityScheme model that allows for more specific type checking on the @useAuth decorator.

We need to remove an openapi3 test that checks for an error when providing an unsupported auth type.
Now the compiler enforces that the auth type is AuthType, and openapi3 supports all of the types in AuthType, it should not be possible to trigger this condition in TSP.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/microsoft/typespec/@typespec/http@9126

commit: 265b0b9

[github-actions]

All changed packages have been documented.

• ✅ @typespec/http

Show changes

@typespec/http - fix ✏️

Allow for OAuth2 scopes to be properly specified with descriptions

[timotheeguerin]

Some previous idea here was to allow an enum instead what do you think

[steverice]

Do you mean that instead of using OAuth2Scope, you would define scopes as e.g.

enum MyScopes {
  Read: "Read public data",
  Write: "Write private data",
}

?

If so, I like it. I like that it gives you a convenient way to reference individual scopes.

Are there any other places where we employ enums this way (enum value is documentation / description)?

[timotheeguerin]

yeah exactly, we do for the version enum where the value is the api version(though that also could be left to interpretation)

[steverice]

Sounds good; I'll make that change.