rails-autodoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e4f22ef7135e62a30d860bcd3d2699faaf58761d939d5dfbcdc9178a7a966d72
+  data.tar.gz: 37dab719fd77a94c028996d8fdd3d825402ce0ddf783efa73bd920f0ee9ce974
+SHA512:
+  metadata.gz: 88f4243ffe758b0b2a1d404b2e92bccae414287e2dfdb87d5689db0fa2ffddf2d0c6f6aa795f68eca74a2e09b122b87bd31a9a174cf14f104945f15dbbe798ed
+  data.tar.gz: 7804faf206a733d660eee91e8c3719e63767c963226c04c988d2d548ba96c17b67a6d5e48fc2560560a9abe4670a6acdd5b10813d4c1a6131129eda8f2bb6449

data/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ["3.2", "3.3"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+          bundler: "2.6.9"
+      - name: Run RuboCop
+        run: bundle exec rubocop
+      - name: Run specs
+        run: bundle exec rspec
+      - name: Verify generated OpenAPI spec
+        run: bundle exec rake autodoc:verify
+
+  appraisal:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Rails 5.2 is not compatible with Ruby 3.x (middleware keyword-arg breakage).
+          - ruby: "2.7"
+            appraisal: "rails-5-2"
+            bundler: "2.4.22"
+          - ruby: "3.2"
+            appraisal: "rails-6-1"
+            bundler: "2.6.9"
+          - ruby: "3.2"
+            appraisal: "rails-7-0"
+            bundler: "2.6.9"
+          - ruby: "3.2"
+            appraisal: "rails-7-1"
+            bundler: "2.6.9"
+          - ruby: "3.2"
+            appraisal: "rails-8-0"
+            bundler: "2.6.9"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler: ${{ matrix.bundler }}
+      - name: Install root gems
+        run: bundle install
+      - name: Generate appraisal gemfiles
+        run: bundle exec appraisal generate
+      - name: Install appraisal gemfile
+        run: bundle exec appraisal ${{ matrix.appraisal }} bundle install
+      - name: Run appraisal specs
+        run: bundle exec appraisal ${{ matrix.appraisal }} rake spec

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc/
+/_yardoc/
+/coverage/
+/doc/
+/gemfiles/.bundle/
+/pkg/
+/spec/dummy/log/
+/spec/dummy/openapi/*.yaml
+!/spec/dummy/openapi/.keep
+/spec/dummy/tmp/
+/spec/examples.txt
+/tmp/
+/vendor/bundle/
+/.DS_Store
+*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,81 @@
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "spec/dummy/**/*"
+    - "vendor/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/OptionalBooleanParameter:
+  Exclude:
+    - "lib/rails_autodoc/dsl/controller_extensions.rb"
+    - "lib/rails_autodoc/registry.rb"
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Layout/EndOfLine:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - "lib/rails_autodoc/tasks/autodoc.rake"
+
+Lint/DuplicateBranch:
+  Exclude:
+    - "lib/**/*"
+
+Naming/PredicateMethod:
+  Exclude:
+    - "lib/rails_autodoc/configuration.rb"
+    - "lib/rails_autodoc/generator.rb"
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "Appraisals"
+    - "rails-autodoc.gemspec"
+
+Metrics/ClassLength:
+  Exclude:
+    - "lib/rails_autodoc/openapi_spec_builder.rb"
+    - "lib/rails_autodoc/strong_params_parser.rb"
+    - "lib/rails_autodoc/schema_mapper.rb"
+    - "lib/rails_autodoc/response_inferencer.rb"
+
+Metrics/MethodLength:
+  Max: 30
+  Exclude:
+    - "lib/rails_autodoc/openapi_spec_builder.rb"
+
+Metrics/ParameterLists:
+  Exclude:
+    - "lib/rails_autodoc/openapi_spec_builder.rb"
+    - "lib/rails_autodoc/route_inspector.rb"
+
+Metrics/AbcSize:
+  Exclude:
+    - "lib/rails_autodoc/openapi_spec_builder.rb"
+    - "lib/rails_autodoc/strong_params_parser.rb"
+    - "lib/rails_autodoc/route_inspector.rb"
+
+Metrics/CyclomaticComplexity:
+  Max: 14
+  Exclude:
+    - "lib/rails_autodoc/openapi_spec_builder.rb"
+    - "lib/rails_autodoc/response_inferencer.rb"
+    - "lib/rails_autodoc/strong_params_parser.rb"
+
+Metrics/PerceivedComplexity:
+  Max: 18
+
+Style/ClassVars:
+  Exclude:
+    - "app/controllers/rails_autodoc/spec_controller.rb"

data/.yardopts

@@ -0,0 +1,3 @@
+--markup markdown
+--files lib
+--output docs/api

data/Appraisals

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+appraise "rails-5-2" do
+  gem "rails", "~> 5.2.8"
+  gem "sqlite3", "~> 1.4.4"
+end
+
+appraise "rails-6-1" do
+  gem "rails", "~> 6.1.7"
+  gem "sqlite3", "~> 1.4.4"
+end
+
+appraise "rails-7-0" do
+  gem "rails", "~> 7.0.8"
+  gem "sqlite3", "~> 1.6.9"
+end
+
+appraise "rails-7-1" do
+  gem "rails", "~> 7.1.5"
+  gem "sqlite3", "~> 1.6.9"
+end
+
+appraise "rails-8-0" do
+  gem "rails", "~> 8.0.0"
+  gem "sqlite3", ">= 2.1"
+end

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-24
+
+### Added
+
+- Initial release of `rails-autodoc`
+- Automatic OpenAPI 3.0.3 generation from Rails routes, strong params, and `db/schema.rb`
+- AST-based `permit(...)` extraction for request body schemas
+- Response inference from `render json:` and `head` calls
+- Serializer adapters for Alba, Blueprinter, and ActiveModel::Serializer
+- Optional `swagger_doc` annotation DSL for overrides
+- Swagger UI engine mount at `/api-docs`
+- Rake tasks: `autodoc:generate`, `autodoc:verify`, `autodoc:routes`
+- Install generator: `rails generate rails_autodoc:install`
+- Rails 5.2 through 8.x Appraisal test matrix
+- Documentation site and contributor guides

data/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to rails-autodoc
+
+Thank you for contributing. This gem generates OpenAPI documentation from Rails conventions, so changes should preserve backward compatibility across Rails 5.2 through 8.x whenever possible.
+
+## Development setup
+
+```bash
+git clone https://github.com/example/rails-autodoc.git
+cd rails-autodoc
+bundle install
+bundle exec rspec
+```
+
+## Testing against multiple Rails versions
+
+```bash
+bundle exec appraisal install
+bundle exec appraisal rake spec
+```
+
+The Combustion dummy app lives in `spec/dummy/`.
+
+## Adding AST fixture cases
+
+1. Add a controller snippet under `spec/fixtures/controllers/`
+2. Add expectations in `spec/rails_autodoc/strong_params_parser_spec.rb`
+3. If output changes globally, update golden files in `spec/fixtures/expected_specs/`
+
+## Adding a serializer adapter
+
+1. Create `lib/rails_autodoc/serializers/your_adapter.rb`
+2. Subclass `RailsAutodoc::Serializers::Base`
+3. Register it in `lib/rails_autodoc/serializers/registry.rb`
+4. Add unit tests under `spec/rails_autodoc/serializers/`
+
+## Code style
+
+- Run `bundle exec rubocop` before opening a PR
+- Keep public APIs documented with YARD comments
+- Prefer small, focused classes over large monoliths
+
+## Documentation
+
+- Update `README.md` for user-facing changes
+- Update relevant pages under `docs/` for behavior or configuration changes
+- Add entries to `CHANGELOG.md` under `[Unreleased]`
+
+## Pull request checklist
+
+- [ ] Specs pass locally (`bundle exec rspec`)
+- [ ] Appraisal matrix passes for affected Rails versions
+- [ ] `bundle exec rake autodoc:verify` passes on the dummy app
+- [ ] Documentation updated
+- [ ] CHANGELOG updated

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rails", "~> 7.1"
+gem "sqlite3", "~> 1.6.9"
+# nokogiri 1.15.x does not support Ruby 3.3+ (CI matrix)
+gem "nokogiri", ">= 1.16.8"

data/Gemfile.lock

@@ -0,0 +1,298 @@
+PATH
+  remote: .
+  specs:
+    rails-autodoc (0.1.0)
+      activesupport (>= 5.2, < 9)
+      parser (~> 3.3)
+      psych (>= 3.1)
+      railties (>= 5.2, < 9)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (7.1.6)
+      actionpack (= 7.1.6)
+      activesupport (= 7.1.6)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (7.1.6)
+      actionpack (= 7.1.6)
+      activejob (= 7.1.6)
+      activerecord (= 7.1.6)
+      activestorage (= 7.1.6)
+      activesupport (= 7.1.6)
+      mail (>= 2.7.1)
+      net-imap
+      net-pop
+      net-smtp
+    actionmailer (7.1.6)
+      actionpack (= 7.1.6)
+      actionview (= 7.1.6)
+      activejob (= 7.1.6)
+      activesupport (= 7.1.6)
+      mail (~> 2.5, >= 2.5.4)
+      net-imap
+      net-pop
+      net-smtp
+      rails-dom-testing (~> 2.2)
+    actionpack (7.1.6)
+      actionview (= 7.1.6)
+      activesupport (= 7.1.6)
+      cgi
+      nokogiri (>= 1.8.5)
+      racc
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    actiontext (7.1.6)
+      actionpack (= 7.1.6)
+      activerecord (= 7.1.6)
+      activestorage (= 7.1.6)
+      activesupport (= 7.1.6)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (7.1.6)
+      activesupport (= 7.1.6)
+      builder (~> 3.1)
+      cgi
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (7.1.6)
+      activesupport (= 7.1.6)
+      globalid (>= 0.3.6)
+    activemodel (7.1.6)
+      activesupport (= 7.1.6)
+    activerecord (7.1.6)
+      activemodel (= 7.1.6)
+      activesupport (= 7.1.6)
+      timeout (>= 0.4.0)
+    activestorage (7.1.6)
+      actionpack (= 7.1.6)
+      activejob (= 7.1.6)
+      activerecord (= 7.1.6)
+      activesupport (= 7.1.6)
+      marcel (~> 1.0)
+    activesupport (7.1.6)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      mutex_m
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    appraisal (2.5.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark (0.5.0)
+    bigdecimal (4.1.2)
+    builder (3.3.0)
+    cgi (0.5.1)
+    combustion (1.5.0)
+      activesupport (>= 3.0.0)
+      railties (>= 3.0.0)
+      thor (>= 0.14.6)
+    concurrent-ruby (1.3.6)
+    connection_pool (2.5.5)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    crass (1.0.6)
+    date (3.5.1)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    erb (4.0.4.1)
+      cgi (>= 0.3.3)
+    erubi (1.13.1)
+    globalid (1.3.0)
+      activesupport (>= 6.1)
+    hashdiff (1.2.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.19.5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    loofah (2.25.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.9.0)
+      logger
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.2.1)
+    mini_mime (1.1.5)
+    mini_portile2 (2.8.9)
+    minitest (5.26.1)
+    mutex_m (0.3.0)
+    net-imap (0.4.24)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.5)
+    nokogiri (1.19.3)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    parallel (1.28.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    public_suffix (5.1.1)
+    racc (1.8.1)
+    rack (3.2.6)
+    rack-session (2.1.2)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.3.1)
+      rack (>= 3)
+    rails (7.1.6)
+      actioncable (= 7.1.6)
+      actionmailbox (= 7.1.6)
+      actionmailer (= 7.1.6)
+      actionpack (= 7.1.6)
+      actiontext (= 7.1.6)
+      actionview (= 7.1.6)
+      activejob (= 7.1.6)
+      activemodel (= 7.1.6)
+      activerecord (= 7.1.6)
+      activestorage (= 7.1.6)
+      activesupport (= 7.1.6)
+      bundler (>= 1.15.0)
+      railties (= 7.1.6)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.7.0)
+      loofah (~> 2.25)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (7.1.6)
+      actionpack (= 7.1.6)
+      activesupport (= 7.1.6)
+      cgi
+      irb
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-rails (7.1.1)
+      actionpack (>= 7.0)
+      activesupport (>= 7.0)
+      railties (>= 7.0)
+      rspec-core (~> 3.13)
+      rspec-expectations (~> 3.13)
+      rspec-mocks (~> 3.13)
+      rspec-support (~> 3.13)
+    rspec-support (3.13.7)
+    rubocop (1.86.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    securerandom (0.3.2)
+    sqlite3 (1.6.9)
+      mini_portile2 (~> 2.8.0)
+    stringio (3.2.0)
+    thor (1.5.0)
+    timeout (0.6.1)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webmock (3.26.2)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    websocket-driver (0.8.0)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.6.18)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  appraisal
+  combustion (~> 1.4)
+  nokogiri (>= 1.16.8)
+  rails (~> 7.1)
+  rails-autodoc!
+  rspec (~> 3.12)
+  rspec-rails
+  rubocop (~> 1.60)
+  sqlite3 (~> 1.6.9)
+  webmock
+
+BUNDLED WITH
+   2.6.9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rails Autodoc Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.