Overview

The APIMatic OpenAPI Linter GitHub App automatically validates and lints your OpenAPI definitions within GitHub repositories. Every time you create or update a pull request, the app ensures your API definitions meet high standards for both code generation and documentation generation, helping you maintain consistency and quality across your API projects.

Features

• Comprehensive Ruleset: Validates OpenAPI definitions using 1200+ built-in rules tailored for code and documentation generation.
• Continuous Validation: Automatically validates OpenAPI files on pull request creation or synchronization.
• GitHub Checks Integration: - Integrates with GitHub’s Checks API to support branch protection rules that block PR merges if errors are found.
• Detailed Audit Reports: Generates shareable validation reports for easy review and collaboration.
• Multi-File Support: Validates multiple OpenAPI definitions within a single repository.
• API Merging Support: Leverages APIMatic’s merging capabilities to seamlessly merge multiple OpenAPI definitions and validate the merged definition.
• Customizable Configurations: Allows you to enable/disable checks, specify OpenAPI file paths, and configure validation rules.

Setup

Follow these steps to get started with the APIMatic OpenAPI Linter GitHub App:

1. Install the GitHub App

• To install the app, click the button located in the top right corner of this page.

2. Authorize with APIMatic

• Once installed, you will be redirected to authenticate the app with your APIMatic account. Please ensure the authorization is completed before proceeding.

3. Configure Your Repository

• In the root of your repository, create a .apimaticsettings.json configuration file. This file will define the paths to your OpenAPI definition files and other settings. Example:

{
  "OpenAPIDefinitionPaths": [
    "path/to/your/openapi/directory",
    "path/to/your/openapi/file.json",
    "path/to/your/openapi/file.yaml",
  ],
  "IgnoreValidationErrors": false
}

• OpenAPIDefinitionPaths: Array of paths to your OpenAPI definition files or directories.
• IgnoreValidationErrors: Set to true to ignore validation errors (use with caution).

4. Validate OpenAPI Definitions on Pull Requests

Once set up, the app automatically validates your OpenAPI definitions every time a pull request is created or updated.

Usage

Validation on Pull Request

When you create or synchronize a pull request, the APIMatic OpenAPI Linter will:

• Validate the OpenAPI definition files listed in the .apimaticsettings.json file.
• Post a summary of the validation results in the pull request comments.
• Provide a link to the full validation report for detailed insights.

GitHub Checks Integration

The app integrates with GitHub's Checks API, enabling you to track the validation status directly within GitHub.

• Passed Validation: Merges are allowed.
• Failed Validation: Merges are blocked until errors are resolved. (Assuming you have branch protection rules set up on the repository).

You can set the validation check as a required status in your branch protection rules to ensure that only pull requests whose validation has passed are merged.

Example Workflow

1. Push OpenAPI Definitions
   Push or update your OpenAPI files to your repository.

2. Push Configuration File
   Add root level configuration file (if not defined already) and make sure you have defined the paths of the OpenAPI definitions in the configuration file.

3. Create or Update Pull Request
   Open a pull request to merge your changes.

4. Automatic Validation
   The APIMatic OpenAPI Linter runs validation on your OpenAPI files.

5. PR Comment & Status Update
   The app posts a comment with validation results and a link to the full report. GitHub checks will display the validation status.

Additional Configuration Options

Customizing Validation Rules

APIMatic's OpenAPI Linter offers extensive customization for validation rules. The app includes over 1,200 out-of-the-box rules, and you can:

• Configure the validation by enabling or disabling specific rule or rulesets and much more.
• Add custom rules for specialized validations

For more details, check out APIMatic's rulesets documentation.

Additional Resources

• APIMatic VSCode Extension
  Enhance your local development environment with the APIMatic VSCode extension for real-time validation, automatic error fixing, and rule configuration directly within Visual Studio Code.

Support

If you have any questions or issues, feel free to reach out to our support team.