Feat: automated Open API syntax validation on submitting PR to master

[homosapien14]

Description (fixes #366 )

Problem: Sometimes when pull requests are merged, syntactical errors in the OpenAPI document get committed to the master branch, which can lead to integration issues and broken functionality.

Feature Request: Implement an automated script that validates OpenAPI specifications when a pull request is created. The script should specifically validate transaction.yaml, meta.yaml, and registry.yaml against the OpenAPI 3.0 specification.

Goals:

• Create an automated workflow that triggers on pull requests and pushes to the master branch.
• Validate transaction.yaml, meta.yaml, and registry.yaml to ensure they conform to the OpenAPI 3.0 specification.

Solution

How I Solved It:

Workflow Configuration:

• Configured a GitHub Actions workflow to run on both push events to the master branch and pull requests targeting the master branch.
• Added steps to:
  • Checkout the code.
  • Set up Node.js.
  • Install the openapi-cli tool globally.
  • Ensure the validation script (validate-openapi.sh) is executable.
  • Execute the validation script to check OpenAPI files for syntax errors.

Validation Script:

• Created validate-openapi.sh to iterate over the OpenAPI files (transaction.yaml, meta.yaml, and registry.yaml).
• The script uses openapi lint to check for errors and warnings. If any issues are found, it reports them and exits with a non-zero status.

Expected Outcome

• Specs on Master Branch:
  • The OpenAPI specifications on the master branch should not have any syntax errors after a successful PR merge.

Acceptance Criteria

• Error Handling:
  • The workflow should fail if syntax errors are present in the OpenAPI spec during a PR check.
• Success Criteria:
  • The workflow should pass if no syntax errors are found in the OpenAPI spec during a PR check.

How to Test

1. Create a Pull Request:

   • Make changes to the OpenAPI files (transaction.yaml, meta.yaml, registry.yaml) in a new branch and open a pull request targeting the master branch.

2. Check Workflow Execution:

   • Ensure the GitHub Actions workflow runs automatically.
   • Verify that the validation steps execute correctly.

3. Test with Errors:

   • Introduce syntactical errors in the OpenAPI files and observe if the workflow fails and reports the errors.

4. Test without Errors:

   • Ensure that a PR with valid OpenAPI files passes the checks successfully without any errors.

[homosapien14]

@ravi-prakash-v Hii , could you please review it once.

[homosapien14]

@rajaneeshk90 can you please look at this?

[VedantKhairnar]

Hello @harshcrop Will you pls review the contribution? Thanks.

[homosapien14]

hey @harshcrop , can you even give me a feedback?

[rajaneeshk90]

Hi @homosapien14,

Thank you for submitting the PR! I appreciate your effort.

I have a few suggestions that could help improve the submission:

• Could you please provide more detailed steps to verify that the changes are working as intended?
• The changes to the api/meta/build/meta.yaml file aren't necessary, so they can be removed.
• It would be better to avoid using a shell script for the validation process.

Thanks again for your contribution!

Best regards, Rajaneesh

[VedantKhairnar]

Hello @homosapien14 Any update on this? Also, Augtoberfest ends on 15th Sept, so it would be great if we finish this before that. Thanks.

[homosapien14]

Hi @rajaneeshk90, Thank you for your response. I am sorry for the delay (I was busy with the office project deadline).

I have made the required changes as you suggested in this 82fa17b commit.

How to Test the Changes

1. Create a New Branch:

   • First, create a new branch from swapnil/openapispecs.
   • Update the push branches in the validate-openapi.yml file to your new branch name (xyz).
   • Push the changes to the remote repository.

2. Test the Workflow:

   • Create a new branch from master and make invalid changes (e.g., introduce syntax errors or remove required lines) in the meta.yaml, registry.yaml, or transaction.yaml files.

3. Push and Create a Draft PR:

   • Push the invalid changes to the remote repository.
   • Create a draft pull request with the target branch set to xyz.

4. Check the CI Workflow:

   • The GitHub Actions workflow will run automatically.
   • It should throw an error in the CI step if there are any issues with the OpenAPI files, such as syntax problems or missing fields.

   Here are the sample errors while I was testing the implementation: