Implement use of linting rule set for Blockchain Public Address API

[PedroDiez]

Problem description
Implement use of linting rule set for Blockchain Public Address API.
what we have to do is well documented in Commonalities:
camaraproject/Commonalities#110
camaraproject/Commonalities#74

Expected action
Check our API with linting rule set
provide feedback to commonalities team

Additional context
cc: @rartych who asked project volunteer to perform this action.

[PedroDiez]

25/ENE/24: Being able to apply Linter. Next step is to check linter output and made adjustments in two directions:

• The ones that apply in API spec
• The refinements in linter configuration for BlockcahinPublicAddress applicability

[PedroDiez]

LINTER RULES OUTPUT

Run spectral lint code/API_definitions/blockchain_public_address.yaml --verbose --ruleset .spectral.yml
spectral lint code/API_definitions/blockchain_public_address.yaml --verbose --ruleset .spectral.yml
shell: /usr/bin/bash -e {0}
env:
APPLY_FIXES: all
APPLY_FIXES_EVENT: pull_request
APPLY_FIXES_MODE: commit
Found 65 rules (56 enabled)
Linting /home/runner/work/BlockchainPublicAddress/BlockchainPublicAddress/code/API_definitions/blockchain_public_address.yaml
warning camara-reserved-words Reserved words found in input: Consider avoiding the use of reserved word 'public' /blockchain-public-addresses
warning camara-reserved-words Reserved words found in input: Consider avoiding the use of reserved word 'public' /blockchain-public-addresses/{id}

/home/runner/work/BlockchainPublicAddress/BlockchainPublicAddress/code/API_definitions/blockchain_public_address.yaml
46:7 warning camara-path-param-id Path Parameter Naming Warning: Use 'resource_id' instead of just 'id' in path parameters. paths
47:32 error camara-parameter-casing-convention /blockchain-public-addresses should be kebab-case: must be kebab case paths./blockchain-public-addresses
58:13 warning oas3-operation-security-defined "blockchain-public-address:read" must be listed among scopes. paths./blockchain-public-addresses.get.security[0].openId[0]
114:13 warning oas3-operation-security-defined "blockchain-public-address:create" must be listed among scopes. paths./blockchain-public-addresses.post.security[0].openId[0]
152:37 error camara-parameter-casing-convention /blockchain-public-addresses/{id} should be kebab-case: must be kebab case paths./blockchain-public-addresses/{id}
163:13 warning oas3-operation-security-defined "blockchain-public-address:delete" must be listed among scopes. paths./blockchain-public-addresses/{id}.delete.security[0].openId[0]
191:12 warning camara-parameters-descriptions Parameter description is missing or empty: "openId.description" property must be truthy components.securitySchemes.openId
207:13 warning camara-path-param-id Path Parameter Naming Warning: Use 'resource_id' instead of just 'id' in path parameters. components.parameters.Id.name
311:15 warning camara-parameters-descriptions Parameter description is missing or empty: "ErrorInfo.description" property must be truthy components.schemas.ErrorInfo
344:21 error oas3-valid-media-example "value" property must have required property "status" components.responses.InvalidArgumentForBlockchain400.content.application/json.examples.InvalidArgument.value
348:21 error oas3-valid-media-example "value" property must have required property "status" components.responses.InvalidArgumentForBlockchain400.content.application/json.examples.InvalidBlockchainNetworkId.value
352:21 error oas3-valid-media-example "value" property must have required property "status" components.responses.InvalidArgumentForBlockchain400.content.application/json.examples.InvalidCurrencyForBlockchain.value
356:21 error oas3-valid-media-example "value" property must have required property "status" components.responses.InvalidArgumentForBlockchain400.content.application/json.examples.RequiredCurrencyforBlockchain.value
373:21 error oas3-valid-media-example "value" property must have required property "status" components.responses.PermissionDeniedForBlockchain403.content.application/json.examples.PermissionDenied.value
377:21 error oas3-valid-media-example "value" property must have required property "status" components.responses.PermissionDeniedForBlockchain403.content.application/json.examples.NotAllowedBlockchainNetworkId.value

[PedroDiez]

Considerations/Feedback:

• 1. warning camara-reserved-words Reserved words found in input: Consider avoiding the use of reserved word 'public' /blockchain-public-addresses. NOTE: Action is adjust linter to skip this in Blockchain, no sense to trigger warning. Up to CAMARA Commonalities WG to consider a default rule
• 2. 46:7 warning camara-path-param-id Path Parameter Naming Warning: Use 'resource_id' instead of just 'id' in path parameters. paths: OK to the warning, {id} can be kept. No additional action
• 3. 47:32 error camara-parameter-casing-convention /blockchain-public-addresses should be kebab-case: must be kebab case paths./blockchain-public-addresses: report to Commonalities as the endpoint path is already kebab-case. Seems it needs adjustments
• 4. 58:13 warning oas3-operation-security-defined "blockchain-public-address:read" must be listed among scopes. paths./blockchain-public-addresses.get.security[0].openId[0]: Not sure what to do with this kind of warning.
• 5. 191:12 warning camara-parameters-descriptions Parameter description is missing or empty: "openId.description" property must be truthy components.securitySchemes.openId: Not sure what to do with this kind of message. Maybe set a description: openId security schema (to be applied in the same way in all APIs)?
• 6. 311:15 warning camara-parameters-descriptions Parameter description is missing or empty: "ErrorInfo.description" property must be truthy components.schemas.ErrorInfo: Not sure what to do with this kind of message. Maybe set a description: Error Model for CAMARA APIs (to be applied in the same way in all APIs)?
• 7. 344:21 error oas3-valid-media-example "value" property must have required property "status": These kind of errors need to be fixed in API Spec. Trigger new PR to cover this

[PedroDiez]

@rartych, any consideration in how to proceed with topics iv, v, and vi?

[rartych]

Thanks @PedroDiez, my comments:

ii. https://github.com/camaraproject/Commonalities/blob/API-linting-Implementation-Guideline/documentation/API-design-guidelines.md#34-path-parameters-use

3. It is recommended that the identifier have a similar morphology on all endpoints. For example, “xxxxId”, where xxx is the name of the entity it references:
   /users/{userId}
   /accounts/{accountId}

iii. was false positive - corrected in final version of linting rules
iv. rule removed as not fully compatible with OpenIdConnect
v. and vi. if adding description does not make sense then ignore the warning

[PedroDiez]

After Linter execution with configuration as per: camaraproject/Commonalities@29e4e9d

OutPut:

Need to check output in detail:
https://github.com/PedroDiez/BlockchainPublicAddress/actions/runs/7759672690/job/21164236006?pr=1

Seems False-Positive case (kebab-case checking) is working well, so fixed cc @rartych

[PedroDiez]

Regarding Errors:

• Some of them are already covered by enhancements_from_linter_rules #40
• Rest need to check actions in yaml. Will take advantage of PR#40

cc @rartych

[PedroDiez]

Now Linter has good refinement. Pending errors are format related "ones"

code/API_definitions/blockchain_public_address.yaml
Error: 10:1 [trailing-spaces] trailing spaces
Error: 58:11 [indentation] wrong indentation: expected 12 but found 10
Error: 114:11 [indentation] wrong indentation: expected 12 but found 10
Error: 163:11 [indentation] wrong indentation: expected 12 but found 10
Error: 241:1 [trailing-spaces] trailing spaces
Error: 257:17 [trailing-spaces] trailing spaces
Error: 293:1 [trailing-spaces] trailing spaces
Error: 309:17 [trailing-spaces] trailing spaces

cc @rartych, @grgpapadopoulos I will generate new PR to fix them.

Regarding the working of linter rules is fine for Blockchain Public Address

[PedroDiez]

Test with current specification after format updates and newest linter configuration from Commonalities

[PedroDiez]

After latest check:

❌ Linted [YAML] files with [yamllint]: Found 1 error(s) - (0.33s) (expand for details)

• Using [yamllint v1.32.0] https://megalinter.io/7.3.0/descriptors/yaml_yamllint
• MegaLinter key: [YAML_YAMLLINT]
• Rules config: [/github/workspace/.yamllint.yaml]
• Number of files analyzed: [1]
  --Error detail:
  code/API_definitions/blockchain_public_address.yaml
  Error: 293:1 [trailing-spaces] trailing spaces

Need to check spec