Introducing a more flexible and efficient way to validate your OpenAPI definitions with our GitHub App! The new Filepath Workflow allows you to specify the exact path to your main OpenAPI file, making it easier to manage and validate complex or modular API projects. This update streamlines the validation process, reduces unnecessary checks, and ensures your API definitions are always up to standard.
Details
Previously, our GitHub app supported two workflows for OpenAPI validation:
No Config File Workflow:
If users did not provide any configuration file, the app would automatically validate all OpenAPI files present in the repository. This was a catch-all approach, ensuring nothing was missed, but could be inefficient for large repos or split specifications.Directory Path Workflow:
Users could specify the path to a directory containing their main OpenAPI file in the.apimaticsettings.json
config file. The app would then validate the main file in that directory along with all its referenced files. This allowed for more targeted validation but still required the main file to be in a specific folder.This flow expects your main OpenAPI file and the associated files are available in the directory.
File Path Workflow (New & Improved):
With this new approach, you can now specify the exact path to your main OpenAPI file directly in the .apimaticsettings.json
configuration file. This is especially useful for projects that use split or modular OpenAPI specifications, where the main file references multiple other files scattered throughout your repository.
Here’s how it works:
- You add a
.apimaticsettings.json
file to the root of your repository. - In this file, you specify the path(s) to your main OpenAPI definition file(s) using the
OpenAPIDefinitionPaths
property. - The GitHub app will then:
- Locate the main OpenAPI file at the path you provided.
- Automatically find and validate all files that are referenced (using
$ref
) from your main file, no matter where they are in your repo. - Ensure that your entire API definition—including all its components, schemas, and referenced files—is validated as a single, cohesive unit.
- This workflow is ideal for teams who maintain large, complex APIs with definitions split across multiple files and folders.
Example .apimaticsettings.json
:
{
"OpenAPIDefinitionPaths": [
"MyApi/openapi.yaml"
]
}
Impact:
- Provides more flexibility and control over which OpenAPI files are validated.
- Reduces unnecessary validation runs, speeding up CI workflows.
- Ensures only the intended API definitions are checked.
- Benefits teams with complex or modular API structures.
- Leads to faster feedback and improved API quality.