Integrate rspec-openapi for automatic OpenAPI spec generation

Add rspec-openapi to Gemfile and configure it in spec/support/openapi.rb
to regenerate docs/openapi.yml from request specs when running with
OPENAPI=1. The gem merges actual JSON:API responses into the existing
spec file, preserving hand-written component schemas.

Also includes docs/openapi.yml in the gemspec file list and documents
the workflow in the README.

https://claude.ai/code/session_01F4qY2LA6JYqsvdLi4xkLVA

Author: tvdeyen

Gemfile

@@ -26,3 +26,5 @@ gem "standard", "~> 1.25", require: false
 gem "pry-byebug"
 
 gem "propshaft", "~> 1.3"
+
+gem "rspec-openapi", require: false

README.md

@@ -97,6 +97,30 @@ Alchemy::JsonApi.key_transform = :camel_lower
 
 It defaults to `:underscore`.
 
+## OpenAPI Documentation
+
+The API is documented with an OpenAPI 3.0 spec at `docs/openapi.yml`. When the
+engine is mounted, the spec is served as JSON at:
+
+```
+GET /jsonapi/openapi.json
+```
+
+Point Swagger UI, Redoc, or any OpenAPI client generator at this URL.
+
+### Regenerating the spec
+
+The spec is auto-generated from request specs using
+[rspec-openapi](https://github.com/exoego/rspec-openapi). To update it after
+changing endpoints or serializers:
+
+```bash
+OPENAPI=1 bundle exec rspec
+```
+
+This merges actual API responses into `docs/openapi.yml`. Hand-written component
+schemas are preserved. Review the diff and commit the result.
+
 ## Contributing
 
 Contribution directions go here.

alchemy-json_api.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
   spec.description = "A JSONAPI compliant API for AlchemyCMS"
   spec.license = "BSD-3-Clause"
 
-  spec.files = Dir["{app,config,db,lib}/**/*", "LICENSE", "Rakefile", "README.md"]
+  spec.files = Dir["{app,config,db,docs,lib}/**/*", "LICENSE", "Rakefile", "README.md"]
 
   spec.add_dependency "alchemy_cms", [">= 8.2.0.a", "< 9"]
   spec.add_dependency "jsonapi.rb", [">= 1.6.0", "< 2.2"]

spec/rails_helper.rb

@@ -13,6 +13,7 @@
 require "shoulda-matchers"
 
 require "alchemy/json_api/test_support/ingredient_serializer_behaviour"
+require_relative "support/openapi"
 
 Shoulda::Matchers.configure do |config|
   config.integrate do |with|

spec/support/openapi.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+if ENV["OPENAPI"]
+  require "rspec/openapi"
+
+  RSpec::OpenAPI.path = File.expand_path("../../docs/openapi.yml", __dir__)
+  RSpec::OpenAPI.title = "Alchemy CMS JSON API"
+  RSpec::OpenAPI.application_version = Alchemy::JsonApi::VERSION
+  RSpec::OpenAPI.info = {
+    description: <<~DESC.strip,
+      A JSON:API compliant API for AlchemyCMS.
+
+      All responses follow the JSON:API specification. Use the `include` query parameter to
+      sideload related resources, `filter` for Ransack-based filtering, and `page` for pagination.
+    DESC
+    license: {
+      name: "BSD-3-Clause",
+      url: "https://opensource.org/licenses/BSD-3-Clause"
+    },
+    contact: {
+      name: "AlchemyCMS",
+      url: "https://www.alchemy-cms.com/"
+    }
+  }
+
+  RSpec::OpenAPI.comment = <<~COMMENT
+    This file is auto-generated by rspec-openapi.
+    Run `OPENAPI=1 bundle exec rspec` to regenerate.
+  COMMENT
+
+  RSpec::OpenAPI.servers = [{url: "/jsonapi", description: "Mounted engine path (default)"}]
+  RSpec::OpenAPI.response_headers = %w[ETag Cache-Control Last-Modified]
+  RSpec::OpenAPI.example_types = %i[request]
+
+  # Exclude the openapi endpoint itself from generation
+  RSpec::OpenAPI.ignored_paths = [/openapi/]
+
+  # Tag endpoints by controller name
+  RSpec::OpenAPI.tags_builder = ->(example) {
+    controller = example.metadata.dig(:request, :controller) ||
+      example.metadata[:described_class].to_s
+    case controller
+    when /Admin::LayoutPages/ then ["Admin Layout Pages"]
+    when /Admin::Pages/ then ["Admin Pages"]
+    when /LayoutPages/ then ["Layout Pages"]
+    when /Nodes/ then ["Nodes"]
+    when /Pages/ then ["Pages"]
+    else []
+    end
+  }
+end