Extend the API guidelines with a concrete ruleset

[shilpa-padgaonkar]

Several subprojects could be facing issues currently if API specification contributions are made without performing a linting check. To ensure that we can enable this process in Camara natively, we would need a concrete ruleset to validate the spec files against. This issue is created to propose an extension to the existing guidelines by adding a concrete ruleset.

An example of a subproject requesting such a check can be seen here camaraproject/QualityOnDemand#158

[rartych]

Example of guidelines and corresponding linting rules: https://github.com/team-monite/api-style-guide. The introductory video from ASC2022: API Style Guide Constructor for Everyone

[RubenBG7]

Hi @rartych these linting rules (https://github.com/team-monite/api-style-guide) make collision with CAMARA API Guidelines. Could you clarify me this guide goal?

[shilpa-padgaonkar]

@RubenBG7 : Rafal has just provided this as an example. We are working on providing the ruleset which will be aligned to the guidelines in Camara.

[shilpa-padgaonkar]

camaraproject/WorkingGroups#260

[rartych]

The most widely used tool for linting OAS files is Spectral. We should then base the ruleset on Spectral built-in "oas" ruleset.
If you have any additional rules that validate API Design Guidelines, please indicate in comments.

@RandyLevensalor In QoD subproject you proposed Megalinter. I guest its advantage is integration if linters for different languages and formats, but for CAMARA API definitions we use only YAML and OpenAPI (Spectral) linters.
Since you proposed also Swagger Editor Validator as a separate Github action, we can use the action dedicated to Spectral: https://github.com/stoplightio/spectral-action without Megalinter as an "umbrella tool".
Any views on that?

[jlurien]

I don't have experience with any of Spectral or Megalinter, but seems to be some degree of compatibility between both: https://megalinter.io/latest/descriptors/openapi_spectral/, and Megalinter supports a ruleset defined in Spectral. We may agree on using the ruleset of Spectral if it is more convenient for OAS lintering, and then see which is the best way to integrate it with the Github CI

[RandyLevensalor]

Apologies for the delayed response. I'm traveling this week and won't be able to join the commonalities call.

@jlurien pointed out correctly that Megalinter can be used to run Spectral and other linting tools.

I personally find Megalinter handy, since it not only provides support for other linters within the same GitHub actions, it all takes care of reporting errors. This could be a project by project decision on how they choose to use spectral, assuming we use spectral.

I would advocate for using Spectral for this and begin developing rules in the commonalities repo. There are some basic rules around Open API 3.0 that can be added fairly easily. Some of the guidelines are a bit ambiguous when trying to define them in with a strict schema and it would be useful to clarify the this ambiguity as we write the rules.

[ravindrapalaskar17]

@RandyLevensalor, I tried integration of spectral linting with mega linter in my forked QOD repository of CAMARA, it's working perfectly.

I personally found integration of spectral linting along with mega linter is easier. Plus, we already have implementation of Meagalinter in QOD repository of CAMARA and which is accepted in CAMARA.

We need just add the steps for spectral linting in the configuration of Mega linter and define the spectral rules in .yaml file separately.

[hdamker]

I'm also in favor of using mega linter as frame around other linting tools. In QualityOnDemand we have for example also integrated JAVA linting for the test case implementation within the repository. Markdown linting could be another step (currently disabled within QoD).

I wouldn't recommend a project by project decision, rather we should establish a "central" support for establish the Github actions within the sub projects.

And yes, agree to use spectral linting for the specific rules in CAMARA according to the guidelines.

[Kevsy]

rather we should establish a "central" support for establish the Github actions within the sub projects.

Indeed - governance camaraproject/Commonalities#200 proposes that.

[rartych]

@Kevsy @rkandoi @RandyLevensalor @ravindrapalaskar17 @shilpa-padgaonkar Draft PR#74 opened for further discussion

[rartych]

@RandyLevensalor My observation from trying Gihub action defined in PR #110 is that Megalinter report does not include "warning" information when there is no error detected by given linter.
As we have Spectral rules (from Spectral core set and CAMARA specific) producing warnings they are not reported when all problems with "error" severity are solved. I haven't found if it can be configured within Megalinter - it rather gives green light with no error and red light with at least one error detected.
There is also issue raised by @Kevsy #76 about linting responses severity.
Some rules does not indicate errors, but potential improvement or simplification of API specification - so the warning is the right severity level. Spectral allows also to produce "info" and "hint" responses.