Closed pvdbosch closed 4 months ago
WG is OK to update the rule, I'll work out PR.
PR #172 ready for review
So this also applies to securitySchemes, right?
We currently have this:
components:
securitySchemes:
oauth-socsec:
type: oauth2
description: access using access token retrieved from oauth2 server
flows:
clientCredentials:
tokenUrl: https://placeholder.socialsecurity.be/oauth2endpoint
scopes:
"scope:cbss:api:foreignLegalEntity:consult": consult foreign legal entities
"scope:cbss:api:monitoring": access to health check operation
security:
- oauth-socsec:
- scope:cbss:api:foreignLegalEntity:consult
- scope:cbss:api:monitoring
Indeed. That seems to be the place where a lot of OpenAPI files are not compliant yet, but I can't see a reason why it should be an exception. UpperCamelCase makes it clearer that it's a referenced component.
FYI, I also requested to add a verification to the styleguide validator that the references to the securitySchemes from the "security" definitions (Security Requirement Objects) are correct, bc that's something a lot of editors don't seem to check even though part of the OpenAPI spec.
Name of security schemes defined in SMALS / eHealth / CBSS APIs often start with oauth.
For oauth-socsec
example above this becomes OauthSocSec
? OAuthSocSec
is currently not allowed:
[ERROR] file: openapi.yaml: ln 439: [MANDATORY] [oas-types] Component names SHOULD use UpperCamelCase notation. For abbreviations as well, all letters except the first one should be lowercased. /components/securitySchemes/OAuthSocSec
Indeed only OauthSocSec works.
You could argue whether the guideline applies for "abbreviations: all letters after the first should be lowercase". "OAuth" is short for "Open Authorization" but is it a single abbreviation or two separate ones? The validator can't distinguish a single-letter word or abbreviation though from a real violation.
PR has been merged and will be published next release.
Extend naming guidelines for data types [oas-types] (below) to cover all definitions of components (responses, requestBodies, ...)