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: https://github.com/camaraproject/Commonalities/pull/110 https://github.com/camaraproject/Commonalities/pull/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: https://github.com/camaraproject/Commonalities/pull/110/commits/29e4e9da8b8ca7dd0e435fb8a942ac4ba3952b59

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 https://github.com/camaraproject/BlockchainPublicAddress/pull/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