Update Style Guide to cover securityDefintions

[mikekistler]

The Style Guide should be updated with guidelines for documenting the security schemes supported/required by the API.

And we should add some Spectral rules to enforce these guidelines.

[mikekistler]

The ARM linter already has a rule for securityDefintions:

https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/openapi-authoring-automated-guidelines.md#r2054

Unfortunately, the link in the documentation that supposedly describes the required structure is broken. But I think it probably should be pointing here.

And here's the code that actually implements the rule:

https://github.com/Azure/azure-openapi-validator/blob/master/src/dotnet/OpenAPI.Validator/Validation/SecurityDefinitionsStructure.cs

It looks like it wants very specific values for each of the fields in the security definition, which is fine for ARM but we'll need something more flexible as a general rule for Azure.

[lmazuel]

https://github.com/Azure/autorest/blob/main/docs/generate/authentication.md includes a proposal of syntax that could be used as guidelines for service teams, and be compatible with autorest at the same time

[mikekistler]

Some basic validity and style elements we could/should check are:

• There should be a global security or a security for each operation
• For Oauth2, "scopes" should not be empty
• For Oauth2 security, scopes should not be empty and should be a name in scopes of security scheme

[mikekistler]

Here is a more specific set of rules:

1. There is at least one security scheme.
2. All security schemes are either:

• type: oauth2 (do we care about the flow?) or
• type: apiKey with in: header

1. An oauth2 security scheme defines at least one scope.
2. All scopes defined in an oauth2 security scheme match a pattern:

   https:\/\/[\w-]+(\.[\w-]+)+/[\w-.]+
   

3. There is a global security or every operation has a security (that references a defined security scheme)