rails-openapi-gen 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8628f98cf4d903315e964dbcc45d339778e13ede98bbc0ed87ae26e36ab870be
+  data.tar.gz: c90f264b7bf1345670496fbc96a03f4440177830464af007b271d0af87008ac9
+SHA512:
+  metadata.gz: b2065cbdb52235914fb1609011b1cc3a434c6ab11d82e74009cf5668ece9c317b55cc5d21a5a368a3587388ce9df0993abfb28941621180292706a67073804b0
+  data.tar.gz: 6736fb52b3ca6fd58715ea46fdba2f77ddaab7c40c3182c2a973ae4fd53dc00a145e90d66f91fa98b4f8f3e53d2b34c536d5cfe681af8cebb65f910fe5e4120f

data/CLAUDE.md

@@ -0,0 +1,160 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Rails OpenAPI Gen is a Ruby gem that automatically generates OpenAPI 3.0 specifications from Rails applications. It uses AST parsing to analyze routes, controllers, and Jbuilder templates, relying on `# @openapi` comments as the source of truth for type information.
+
+## Development Commands
+
+**Testing:**
+```bash
+rspec                    # Run all tests
+rspec spec/specific_spec.rb   # Run specific test file
+```
+
+**Linting:**
+```bash
+rubocop                  # Run linter
+rubocop -a              # Auto-fix linter issues
+```
+
+**OpenAPI Generation (for testing):**
+```bash
+# These commands require a Rails app environment
+bin/rails openapi:generate  # Generate OpenAPI spec
+bin/rails openapi:check     # Check for missing comments and uncommitted changes
+```
+
+**Gem Development:**
+```bash
+bundle install          # Install dependencies
+rake -T                 # List available rake tasks
+```
+
+## Architecture
+
+### Core Components
+
+**Main Module** (`lib/rails_openapi_gen.rb`):
+- `RailsOpenapiGen.generate` - Entry point for spec generation
+- `RailsOpenapiGen.check` - Entry point for validation
+- `Generator` class - Orchestrates parsing and generation
+- `Checker` class - Validates missing comments and git status
+
+**Parsers** (`lib/rails_openapi_gen/parsers/`):
+- `RoutesParser` - Extracts routes from Rails application
+- `ControllerParser` - Finds controller actions and locates Jbuilder templates
+- `JbuilderParser` - Uses AST to parse Jbuilder templates and extract JSON structure
+- `CommentParser` - Parses `@openapi` comment annotations with regex
+
+**Generators** (`lib/rails_openapi_gen/generators/`):
+- `YamlGenerator` - Creates split YAML files with $ref support
+
+### Data Flow
+
+1. Parse Rails routes to discover endpoints
+2. For each route, find corresponding controller action
+3. Locate associated Jbuilder template
+4. Parse Jbuilder template using AST to extract JSON structure
+5. Extract `@openapi` comments for type information
+6. Generate split YAML files (main spec + separate paths/schemas)
+
+### Comment Format
+
+The gem uses `# @openapi` comments in Jbuilder templates:
+
+```ruby
+# @openapi id:integer required:true description:"User ID"
+json.id @user.id
+
+# @openapi status:string enum:[active,inactive] description:"User status"  
+json.status @user.status
+```
+
+**Supported attributes:**
+- `type`: Data type (string, integer, boolean, number, array, object)
+- `required`: Whether field is required (true/false)
+- `enum`: Allowed values for the field
+- `description`: Human-readable description
+
+### Conditional Rendering Support
+
+For properties that are conditionally rendered (e.g., inside `if` statements), use the `# @openapi conditional:true` comment:
+
+```ruby
+# @openapi conditional:true
+if @user.profile.present?
+  # @openapi type:object description:"User profile information"
+  json.profile do
+    # @openapi bio:string description:"User biography"
+    json.bio @user.profile.bio
+    
+    # @openapi verified:boolean required:true description:"Whether verified"
+    json.verified @user.profile.verified
+  end
+end
+```
+
+**Conditional behavior:**
+- Properties inside conditional blocks are marked as optional in the OpenAPI schema
+- Even if a conditional property has `required:true`, it will not be included in the schema's `required` array
+- Both the parent property (`profile`) and nested properties (`bio`, `verified`) are marked as conditional
+- This ensures the generated OpenAPI spec accurately reflects that these fields may not always be present
+
+### Missing Comment Handling
+
+Fields without `@openapi` comments are marked as `"TODO: MISSING COMMENT"` in the generated spec. The `openapi:check` task validates that no missing comments exist and that the OpenAPI directory has no uncommitted changes.
+
+### Output Structure
+
+Generated files are organized as:
+```
+openapi/
+  openapi.yaml       # Main OpenAPI file with $ref to other files
+  paths/
+    users.yaml      # Path definitions per controller
+  components/
+    schemas/
+      user.yaml     # Schema definitions per model
+```
+
+## Key Files to Understand
+
+- `lib/rails_openapi_gen.rb` - Main entry points and orchestration logic
+- `lib/rails_openapi_gen/parsers/comment_parser.rb` - Comment parsing logic with regex patterns
+- `lib/rails_openapi_gen/parsers/jbuilder_parser.rb` - AST parsing for JSON structure extraction
+- `examples/user.json.jbuilder` - Example of properly commented Jbuilder template
+
+## Examples
+
+### rails_gen_comment Example
+
+The `examples/rails_gen_comment/` directory contains a complete Rails application demonstrating the **reverse workflow** - importing from an existing OpenAPI specification to generate `@openapi` comments in Jbuilder templates.
+
+**Use case:** You have an existing OpenAPI spec and want to automatically annotate your Jbuilder templates with the appropriate `@openapi` comments.
+
+**Key features demonstrated:**
+- Import existing OpenAPI spec: `RailsOpenapiGen.import('docs/api/openapi.yaml')`
+- Automatic comment generation in Jbuilder files
+- Support for complex nested objects and arrays
+- Conditional rendering patterns
+- Operation-level documentation
+
+**Sample files:**
+- `docs/api/openapi.yaml` - Complete OpenAPI 3.0 specification
+- `app/views/api/users/show.json.jbuilder` - Jbuilder with auto-generated comments
+- `app/views/api/users/_user.json.jbuilder` - Partial template with comments
+
+**Running the import:**
+```bash
+cd examples/rails_gen_comment
+bin/rails runner "RailsOpenapiGen.import('docs/api/openapi.yaml')"
+```
+
+This will analyze the OpenAPI spec and add appropriate `@openapi` comments to your Jbuilder templates, making it easy to maintain consistency between your API documentation and implementation.
+
+## Testing Strategy
+
+The gem is designed to work with existing Rails applications. When testing locally, ensure you have a Rails application environment with routes, controllers, and Jbuilder templates that include `@openapi` comments.

data/README.md

@@ -0,0 +1,164 @@
+# Rails OpenAPI Gen
+
+Rails comment-driven OpenAPI specification generator.
+
+## Overview
+
+rails-openapi-gen analyzes your Rails application's routes.rb, controllers, and jbuilder templates to automatically generate OpenAPI documentation. It uses AST parsing to extract JSON structure and relies on `# @openapi` comments for accurate type information.
+
+## Note
+
+AST analysis alone cannot accurately infer all conditional branches and partial patterns. Type, required status, enum values, and descriptions should be explicitly defined using `# @openapi` comments as the source of truth.
+
+### Limitations
+
+The following Jbuilder patterns are not currently supported:
+
+- **Shorthand array syntax**: `json.array! @items, :id, :name` - This shorthand notation cannot be annotated with `@openapi` comments. Use the block form instead:
+  ```ruby
+  json.array! @items do |item|
+    # @openapi id:integer required:true description:"Item ID"
+    json.id item.id
+    
+    # @openapi name:string required:true description:"Item name"
+    json.name item.name
+  end
+  ```
+
+- **Extract shorthand**: `json.extract! @item, :id, :name` - This shorthand notation cannot be annotated with `@openapi` comments. Use explicit property assignments instead:
+  ```ruby
+  # @openapi id:integer required:true description:"Item ID"
+  json.id @item.id
+  
+  # @openapi name:string required:true description:"Item name"
+  json.name @item.name
+  ```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails-openapi-gen'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Usage
+
+### Comment Format
+
+Add `# @openapi` comments to your jbuilder templates:
+
+```ruby
+# @openapi id:integer required:true description:"User ID"
+json.id @user.id
+
+# @openapi status:string enum:[active,inactive] description:"User status"
+json.status @user.status
+
+# @openapi email:string required:true description:"User email address"
+json.email @user.email
+
+# @openapi created_at:string description:"ISO 8601 timestamp"
+json.created_at @user.created_at.iso8601
+```
+
+### Generate OpenAPI Specification
+
+```bash
+bin/rails openapi:generate
+```
+
+This creates the following structure:
+
+```
+openapi/
+  openapi.yaml       # Main OpenAPI file
+  paths/
+    users.yaml      # Path definitions
+    posts.yaml
+  components/
+    schemas/
+      user.yaml     # Schema definitions
+      post.yaml
+```
+
+### Check for Missing Comments
+
+```bash
+bin/rails openapi:check
+```
+
+This command will:
+- Generate the OpenAPI specification
+- Check for missing `@openapi` comments (marked as "TODO: MISSING COMMENT")
+- Verify no uncommitted changes in the openapi/ directory
+- Exit with code 1 if issues are found
+
+## CI Integration
+
+Add to your CI pipeline:
+
+```yaml
+name: OpenAPI Spec Check
+on: [push, pull_request]
+
+jobs:
+  openapi-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      
+      - name: Generate OpenAPI Spec
+        run: bin/rails openapi:generate
+      
+      - name: Check for missing comments
+        run: |
+          if grep -r "TODO: MISSING COMMENT" openapi/; then
+            echo "❌ Missing @openapi comments!"
+            exit 1
+          fi
+      
+      - name: Check for unexpected diffs
+        run: git diff --exit-code openapi/
+```
+
+## Comment Attributes
+
+- `type`: Data type (string, integer, boolean, number, array, object)
+- `required`: Whether the field is required (true/false)
+- `enum`: Allowed values for the field
+- `description`: Human-readable description
+
+## Features
+
+- ✅ Routes.rb parsing for endpoint discovery
+- ✅ Controller analysis to locate jbuilder templates
+- ✅ AST-based jbuilder parsing with partial support
+- ✅ Comment-driven type annotations
+- ✅ Split YAML generation with $ref support
+- ✅ CI-friendly validation commands
+- 🚧 ActiveRecord model inference (optional, future)
+- 🚧 Serializer support (future)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rails-openapi-gen/rails-openapi-gen.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rails_openapi_gen/configuration.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module RailsOpenapiGen
+  class Configuration
+    attr_accessor :openapi_version, :info, :servers, :route_patterns, :output
+
+    # Initializes configuration with default values
+    def initialize
+      @openapi_version = "3.0.0"
+      @info = {
+        title: default_app_name,
+        version: "1.0.0",
+        description: "API documentation generated by rails-openapi-gen"
+      }
+      @servers = [
+        {
+          url: "http://localhost:3000",
+          description: "Development server"
+        }
+      ]
+      @route_patterns = {
+        include: [/.*/], # Include all routes by default
+        exclude: []      # Exclude nothing by default
+      }
+      @output = {
+        directory: "openapi",
+        filename: "openapi.yaml",
+        split_files: true
+      }
+    end
+
+    # TODO: Loads configuration from Ruby file
+    # @param file_path [String, nil] Path to configuration file (defaults to config/openapi.rb or config/initializers/openapi.rb)
+    # @return [void]
+    def load_from_file(file_path = nil)
+      # TODO: Implement configuration loading from file
+      # This method should load configuration from Ruby files and apply it to the instance
+      return
+    end
+
+    # Returns the full path to the output directory
+    # @return [String] Full output directory path
+    def output_directory
+      if @output[:directory].start_with?('/')
+        @output[:directory]
+      else
+        File.join(Rails.root.to_s, @output[:directory])
+      end
+    end
+
+    # Returns the output filename
+    # @return [String] Output filename
+    def output_filename
+      @output[:filename]
+    end
+
+    # Checks if output should be split into multiple files
+    # @return [Boolean] True if files should be split
+    def split_files?
+      @output[:split_files]
+    end
+
+    # Updates output configuration
+    # @param output_config [Hash] Output configuration hash
+    # @return [void]
+    def update_output_config(output_config)
+      load_output_config(output_config)
+    end
+
+    # Checks if a route path should be included in the OpenAPI spec
+    # @param path [String] Route path to check
+    # @return [Boolean] True if route should be included
+    def route_included?(path)
+      # Check if path matches any include pattern
+      included = @route_patterns[:include].any? { |pattern| path.match?(pattern) }
+      return false unless included
+
+      # Check if path matches any exclude pattern
+      excluded = @route_patterns[:exclude].any? { |pattern| path.match?(pattern) }
+      !excluded
+    end
+
+    private
+
+    # Loads Ruby configuration file
+    # @param file_path [String] Path to configuration file
+    # @return [void]
+    def load_ruby_config(file_path)
+      # Load Ruby configuration file
+      # The file should call RailsOpenapiGen.configure block
+      load file_path
+      
+      # Copy configuration from global singleton to this instance
+      global_config = RailsOpenapiGen.configuration
+      @openapi_version = global_config.openapi_version
+      @info = global_config.info.dup
+      @servers = global_config.servers.dup
+      @route_patterns = global_config.route_patterns.dup
+      @output = global_config.output.dup
+    end
+
+    # Returns default application name
+    # @return [String] Default app name
+    def default_app_name
+      if defined?(Rails) && Rails.application
+        Rails.application.class.respond_to?(:module_parent_name) ? 
+          Rails.application.class.module_parent_name : 
+          "RailsApp"
+      else
+        "API"
+      end
+    end
+
+    # Converts hash keys to symbols
+    # @param hash [Hash] Hash to convert
+    # @return [Hash] Hash with symbolized keys
+    def symbolize_keys(hash)
+      return hash unless hash.is_a?(Hash)
+      hash.transform_keys(&:to_sym)
+    end
+
+
+    # Loads output configuration settings
+    # @param output_config [Hash] Output configuration hash
+    # @return [void]
+    def load_output_config(output_config)
+      output_settings = symbolize_keys(output_config)
+      
+      @output[:directory] = output_settings[:directory] if output_settings[:directory]
+      @output[:filename] = output_settings[:filename] if output_settings[:filename]
+      @output[:split_files] = output_settings[:split_files] if output_settings.key?(:split_files)
+    end
+  end
+
+  class << self
+    attr_writer :configuration
+
+    # Returns the configuration instance
+    # @return [Configuration] Configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configures the gem via block
+    # @yield [Configuration] Configuration instance
+    # @return [void]
+    def configure
+      yield(configuration)
+    end
+
+    # Resets configuration to defaults
+    # @return [void]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/rails_openapi_gen/engine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RailsOpenapiGen
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsOpenapiGen
+
+    rake_tasks do
+      load File.expand_path("tasks/openapi.rake", __dir__)
+    end
+  end
+end