How mkon/openapi_contracts works
Project Type and Purpose
• This is a Ruby gem focused on using OpenAPI documentation as an API contract.
• It is meant to work within applications (especially Rails apps) to verify that API requests and responses adhere to the contract defined in an OpenAPI schema.
• It integrates with RSpec by providing matchers that assert responses against the OpenAPI document.
• Additionally, it supplies coverage reporting to indicate how thoroughly the API endpoints are tested.
File Structure
• Top-level directories include:
• “lib” where the core Ruby modules reside.
• “spec” with fixtures, test specs, and configurations for RSpec.
• “bin” contains executables (like build, console, release, etc.) for gem management.
• Test/helper directories (e.g., “spec/support”) for test setup.
• The “lib/openapi_contracts” directory is further subdivided into components like:
• “doc” which deals with OpenAPI document processing (headers, operation, parameters, paths, etc.).
• “coverage” which handles reporting and storing test coverage for API endpoints.
• “parser” to process and transform the OpenAPI file(s).
• “validators” to compare API responses (and optionally requests) against the OpenAPI definitions.
• Other supporting files such as “operation_router” and a helper module.
• Notice presence of RSpec matcher files and integration tests inside “spec” that validate the system’s functionality.
README for Additional Insights
• The README clearly explains that the gem:
• Parses an OpenAPI document, usually stored in “spec/fixtures/openapi/…”.
• Provides RSpec matchers (e.g., match_openapi_doc) for validating HTTP requests/responses.
• Validates different aspects (headers, http status, body, request body, parameters, etc.) by using json_schemer.
• Supports coverage reporting and merging of reports, which is an important part of the system.
• The operational workflow implies that a parsed document (using OpenapiContracts::Doc.parse) is used as a basis for all validation steps.
• Main Components to Include:
• OpenAPI Document Parser: Represents the component (lib/openapi_contracts/parser) that transforms raw OpenAPI YAML files into a structured format for further use.
• API Documentation Component: (lib/openapi_contracts/doc) handling representation and abstraction of API operations, paths, parameters, headers, etc.
• Validator/Matcher Component: (lib/openapi_contracts/validators and lib/openapi_contracts/match.rb) that compares actual responses (and optionally requests) from tests against the schema.
• Operation Router: (lib/openapi_contracts/operation_router) maps incoming requests (identified by method and path) to the correct documentation definitions.
• Coverage Reporting: (lib/openapi_contracts/coverage) stores and generates reports on which endpoints or responses have been validated.
• RSpec Integration: A connector layer where the gem’s matchers (for example match_openapi_doc) integrate with RSpec, using hooks like before(:suite) and after(:suite) to set up and report test coverage.
• Relationships and Interactions:
• The RSpec tests begin by invoking the Parser to load the OpenAPI document.
• The parsed document is represented in the documentation component.
• When a test executes, the Validator/Matcher component uses the API Documentation to validate the HTTP response.
• The Operation Router helps resolve dynamic paths to their schema definition.
• Throughout tests, coverage information is collected and later consolidated by the Coverage module.
• Architectural Patterns and Design Principles:
• Separation of Concerns: Each module (parsing, documenting, validating, and reporting) has a dedicated responsibility.
• Extensibility: The modular design (with separate components for operations like headers, parameters, etc.) allows for future enhancements such as validating Webmock stubs.
• Integration with external tools: Leveraging RSpec and json_schemer for validation.
• Technologies and Frameworks:
• Ruby language (with emphasis on gem-based development).
• RSpec for testing and matchers.
• JSON Schema validation tools (json_schemer) for schema checks.
• CI/CD integration (as seen by the .github directory and workflows).