How exoego/rspec-openapi works
Main Components
• Core Library (located in lib/rspec/openapi):
• Components such as the OpenAPI schema builder, schema merger, schema cleaner, record builder/recorder, hash/key transformers, and shared/extractor hooks.
• Specific extractors for different frameworks (Rails, Rack, Hanami) visible under lib/rspec/openapi/extractors.
• RSpec hooks and integration code (for example, rspec_hooks.rb and shared_hooks.rb).
• Integration Points:
• RSpec integration (hooking into RSpec tests to capture API calls)
• Minitest support (configured through minitest_hooks.rb and examples in spec/minitest)
• User configuration (via module-level assignments in the README examples, supporting dynamic behavior like setting paths, titles, server details, etc.)
• Output Module:
• The component takes the captured request/response data and generates or updates the OpenAPI specification file (e.g. doc/openapi.yaml or doc/schema.json).
• Sample Applications:
• There are sample/test apps in spec/apps (for Hanami, Rails, and Roda) which illustrate how request specs are written across frameworks and how the gem integrates with them.
• CI/CD and Quality Tools:
• The project includes a .github directory with workflows for testing, RuboCop, and CodeQL analysis, ensuring code quality and security during the build process.
Relationships and Data Flow
• The process can be diagrammed as a pipeline:
• Start at the “Test Suite” (RSpec and Minitest tests written by the user) which make HTTP-like request calls against the sample or live API endpoints.
• These tests are instrumented by the gem’s integration hooks (e.g., rspec_hooks, minitest_hooks) that intercept calls and collect request/response details.
• Following extraction, the “Schema Builder/Merger” module assembles the OpenAPI specification. Modules like schema_builder, schema_merger, schema_sorter, and schema_cleaner work in a pipeline to aggregate and consolidate data—also preserving any manual modifications.
• The final output is written to a documentation file (doc/openapi.yaml or doc/schema.json), which can be used by documentation tools (Swagger UI, Redoc).
Architectural Patterns and Principles
• Modular design: Separating the extraction logic (framework-specific) from the core schema-building logic.
• Hook-based Integration: The gem “plugs into” test frameworks (using RSpec and Minitest hooks) to capture data automatically.
• Configurability: Users can customize various aspects (path, title, request/response headers, etc.) through a Ruby DSL. This dynamic configuration pipeline should be represented.
• Preservation of manual changes: The merging strategy ensures that manually modified parts of the schema are preserved.
Relevant Technologies & Frameworks
• Ruby and RSpec (core language/testing framework) along with Minitest.
• Specific web frameworks showcased in the samples (Rails, Hanami, Roda) – these are not part of the gem per se but demonstrate its integration.
• Continuous integration tools such as CodeQL, RuboCop, and GitHub Actions.
Elements
• Test Suites (RSpec/Minitest tests)
• Hook Layer (RSpec hooks, minitest hooks)
• Extractors (subcomponents for Rails, Hanami, Rack)
• Schema Builder/Merger (modules that construct and merge the OpenAPI specs)
• Output (the generated doc/openapi.yaml or doc/schema.json)
• Configuration/Customization (user settings that influence generation)
• CI/CD Workflows (GitHub Actions for testing, linting, security analysis)
• Core library components
• Integration modules (hooks/extractors)
• External interfaces or output (documentation file, external API documentation tools).
• Optionally, note the additional “sample apps” that demonstrate concrete usage scenarios.