openapi_blocks 0.2.0

data/lib/openapi_blocks/cache.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  class Cache # rubocop:disable Style/Documentation
+    def initialize
+      @store = {}
+      @mutex = Mutex.new
+    end
+
+    def get(key)
+      @store[key]
+    end
+
+    def set(key, value)
+      @mutex.synchronize { @store[key] = value }
+    end
+
+    def invalidate!(key = nil)
+      @mutex.synchronize do
+        key ? @store.delete(key) : @store.clear
+      end
+    end
+
+    def cached?(key)
+      @store.key?(key)
+    end
+  end
+end

data/lib/openapi_blocks/configuration/contact_builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  class Configuration
+    class ContactBuilder # rubocop:disable Style/Documentation
+      def name(value = nil)
+        value ? @name = value : @name
+      end
+
+      def email(value = nil)
+        value ? @email = value : @email
+      end
+
+      def url(value = nil)
+        value ? @url = value : @url
+      end
+
+      def to_h
+        { name: @name, email: @email, url: @url }.compact
+      end
+    end
+  end
+end

data/lib/openapi_blocks/configuration/info_builder.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "contact_builder"
+require_relative "license_builder"
+
+module OpenapiBlocks
+  class Configuration
+    class InfoBuilder # rubocop:disable Style/Documentation
+      def title(value = nil)
+        value ? @title = value : @title
+      end
+
+      def version(value = nil)
+        value ? @version = value : @version
+      end
+
+      def description(value = nil)
+        value ? @description = value : @description
+      end
+
+      def contact(&block)
+        @contact = ContactBuilder.new
+        @contact.instance_eval(&block) if block
+      end
+
+      def license(&block)
+        @license = LicenseBuilder.new
+        @license.instance_eval(&block) if block
+      end
+
+      def to_h
+        {
+          title:       @title,
+          version:     @version,
+          description: @description,
+          contact:     @contact&.to_h,
+          license:     @license&.to_h
+        }.compact
+      end
+    end
+  end
+end

data/lib/openapi_blocks/configuration/license_builder.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  class Configuration
+    class LicenseBuilder # rubocop:disable Style/Documentation
+      def name(value = nil)
+        value ? @name = value : @name
+      end
+
+      def url(value = nil)
+        value ? @url = value : @url
+      end
+
+      def to_h
+        { name: @name, url: @url }.compact
+      end
+    end
+  end
+end

data/lib/openapi_blocks/configuration/security_builder.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  class Configuration
+    class SecurityBuilder # rubocop:disable Style/Documentation
+      attr_reader :schemes
+
+      def initialize
+        @schemes = {}
+      end
+
+      def bearer_token(format: "JWT")
+        @schemes[:bearerAuth] = {
+          type:         "http",
+          scheme:       "bearer",
+          bearerFormat: format
+        }
+      end
+
+      def api_key(name: "X-API-Key", in: :header)
+        @schemes[:apiKey] = {
+          type: "apiKey",
+          name: name,
+          in:   binding.local_variable_get(:in).to_s
+        }
+      end
+
+      def to_h
+        @schemes
+      end
+    end
+  end
+end

data/lib/openapi_blocks/configuration/server_builder.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  class Configuration
+    class ServerBuilder # rubocop:disable Style/Documentation
+      def url(value = nil)
+        value ? @url = value : @url
+      end
+
+      def description(value = nil)
+        value ? @description = value : @description
+      end
+
+      def to_h
+        { url: @url, description: @description }.compact
+      end
+    end
+  end
+end

data/lib/openapi_blocks/configuration/servers_builder.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "server_builder"
+
+module OpenapiBlocks
+  class Configuration
+    class ServersBuilder # rubocop:disable Style/Documentation
+      attr_reader :servers
+
+      def initialize
+        @servers = []
+      end
+
+      def server(&block)
+        s = ServerBuilder.new
+        s.instance_eval(&block) if block
+        @servers << s
+      end
+    end
+  end
+end

data/lib/openapi_blocks/configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "configuration/info_builder"
+require_relative "configuration/servers_builder"
+require_relative "configuration/security_builder"
+
+module OpenapiBlocks
+  class Configuration # rubocop:disable Style/Documentation
+    SUPPORTED_VERSIONS = %w[3.1.0 3.0.3].freeze
+
+    attr_reader   :openapi_version
+    attr_accessor :watch
+
+    def initialize
+      @openapi_version = "3.1.0"
+      @watch           = :development
+      @info            = InfoBuilder.new
+      @servers         = []
+      @security        = nil
+    end
+
+    def openapi_version=(version)
+      unless SUPPORTED_VERSIONS.include?(version.to_s)
+        raise ArgumentError,
+              "Unsupported OpenAPI version: #{version.inspect}. Supported versions: #{SUPPORTED_VERSIONS.join(', ')}"
+      end
+
+      @openapi_version = version.to_s
+    end
+
+    def info(&block)
+      @info.instance_eval(&block) if block
+      @info
+    end
+
+    def servers(&block)
+      builder = ServersBuilder.new
+      builder.instance_eval(&block) if block
+      @servers = builder.servers
+    end
+
+    def security(&block)
+      @security ||= SecurityBuilder.new
+      @security.instance_eval(&block) if block
+      @security
+    end
+
+    def to_h
+      {
+        info:    @info.to_h,
+        servers: @servers.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/openapi_blocks/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module OpenapiBlocks
+  class Engine < Rails::Engine # rubocop:disable Style/Documentation
+    isolate_namespace OpenapiBlocks
+
+    engine_name "openapi_blocks"
+
+    # config.autoload_paths << File.expand_path("app/controllers", __dir__)
+  end
+end

data/lib/openapi_blocks/file_watcher.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  class FileWatcher # rubocop:disable Style/Documentation
+    WATCH_PATTERNS = [
+      "app/openapi/**/*.rb",
+      "app/models/**/*.rb",
+      "config/routes.rb",
+      "db/schema.rb"
+    ].freeze
+
+    def initialize(root_path)
+      @root_path = root_path
+      @mtimes    = {}
+      snapshot!
+    end
+
+    def stale?
+      watched_files.any? do |file|
+        mtime(file) != @mtimes[file]
+      end
+    end
+
+    def snapshot!
+      watched_files.each do |file|
+        @mtimes[file] = mtime(file)
+      end
+    end
+
+    private
+
+    def watched_files
+      WATCH_PATTERNS.flat_map do |pattern|
+        Dir.glob(File.join(@root_path, pattern))
+      end
+    end
+
+    def mtime(file)
+      File.exist?(file) ? File.mtime(file) : nil
+    end
+  end
+end

data/lib/openapi_blocks/middleware.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "file_watcher"
+require_relative "cache"
+
+module OpenapiBlocks
+  class Middleware # rubocop:disable Style/Documentation
+    CACHE_KEY = :openapi_spec
+
+    def initialize(app)
+      @app          = app
+      @cache        = Cache.new
+      @file_watcher = FileWatcher.new(root_path)
+    end
+
+    def call(env)
+      @app.call(env)
+    ensure
+      invalidate_if_stale!
+    end
+
+    private
+
+    def invalidate_if_stale!
+      return unless watch_enabled?
+      return unless @file_watcher.stale?
+
+      @cache.invalidate!(CACHE_KEY)
+      @file_watcher.snapshot!
+    end
+
+    def spec
+      @cache.set(CACHE_KEY, Builder.build) unless @cache.cached?(CACHE_KEY)
+
+      @cache.get(CACHE_KEY)
+    end
+
+    def watch_enabled?
+      watched_envs.include?(current_env)
+    end
+
+    def watched_envs
+      Array(OpenapiBlocks.configuration.watch)
+    end
+
+    def current_env
+      Rails.env.to_sym
+    end
+
+    def root_path
+      Rails.root.to_s
+    end
+  end
+end

data/lib/openapi_blocks/operation_builder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  class OperationBuilder # rubocop:disable Style/Documentation
+    attr_reader :_summary, :_description, :_parameters, :_responses, :_security, :_tags
+
+    def summary(value = nil)
+      value ? @_summary = value : @_summary
+    end
+
+    def description(value = nil)
+      value ? @_description = value : @_description
+    end
+
+    def tags(*values)
+      values.any? ? @_tags = values : @_tags
+    end
+
+    def parameter(name, in:, type:, description: nil, required: false)
+      @_parameters ||= []
+      @_parameters << {
+        name:        name,
+        in:          binding.local_variable_get(:in),
+        type:        type,
+        description: description,
+        required:    required
+      }.compact
+    end
+
+    def response(status, description:, schema: nil)
+      @_responses ||= {}
+      @_responses[status.to_s] = {
+        description: description,
+        schema:      schema
+      }.compact
+    end
+
+    def security(*schemes)
+      @_security = schemes.map { |s| { s => [] } }
+    end
+
+    def no_security!
+      @_security = []
+    end
+
+    def to_h
+      {
+        summary:     @_summary,
+        description: @_description,
+        parameters:  @_parameters,
+        responses:   @_responses,
+        security:    @_security,
+        tags:        @_tags
+      }.compact
+    end
+  end
+end

data/lib/openapi_blocks/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module OpenapiBlocks
+  class Railtie < Rails::Railtie # rubocop:disable Style/Documentation
+    initializer "openapi_blocks.middleware" do |app|
+      app.middleware.use OpenapiBlocks::Middleware
+    end
+
+    initializer "openapi_blocks.autoload", before: :set_autoload_paths do |app|
+      app.config.eager_load_paths << app.root.join("app/openapi")
+    end
+
+    config.to_prepare do
+      Dir[Rails.root.join("app/openapi/**/*.rb")].each { |f| require f }
+    end
+  end
+end

data/lib/openapi_blocks/routing/extractor.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require_relative "operation"
+
+module OpenapiBlocks
+  module Routing
+    class Extractor # rubocop:disable Style/Documentation,Metrics/ClassLength
+      IGNORED_CONTROLLERS = %w[
+        rails/
+        action_mailbox/
+        active_storage/
+        openapi_blocks/
+      ].freeze
+
+      def initialize(app = Rails.application)
+        @app = app
+      end
+
+      def extract
+        routes.each_with_object({}) do |operation, hash|
+          next unless operation.valid?
+
+          hash[operation.path] ||= {}
+
+          operation.verbs.each do |verb|
+            hash[operation.path][verb] = build_operation(operation)
+          end
+        end
+      end
+
+      private
+
+      def routes
+        @app.routes.routes.filter_map do |route|
+          defaults = route.defaults
+          next unless defaults[:controller] && defaults[:action]
+          next if IGNORED_CONTROLLERS.any? { |c| defaults[:controller].start_with?(c) }
+
+          Operation.new(
+            controller: defaults[:controller],
+            action:     defaults[:action],
+            path:       route.path.spec.to_s
+          )
+        end
+      end
+
+      def build_operation(operation) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/CyclomaticComplexity
+        meta = operation_meta(operation)
+        parameters = build_parameters(operation, meta)
+        tags       = build_tags(operation, meta)
+
+        op = {
+          tags:        tags,
+          summary:     meta&._summary || build_summary(operation),
+          operationId: build_operation_id(operation),
+          responses:   meta&._responses ? build_custom_responses(meta) : build_default_responses(operation)
+        }
+
+        op[:description] = meta._description if meta&._description
+        op[:parameters]  = parameters        if parameters.any?
+        op[:requestBody] = build_request_body(operation) if operation.has_body
+        op[:security]    = meta._security if meta&._security
+
+        op
+      end
+
+      def build_tags(operation, meta)
+        return meta._tags if meta&._tags&.any?
+
+        openapi_class = find_openapi_class(operation)
+        return openapi_class._tags if openapi_class&._tags&.any?
+
+        [operation.schema_name]
+      end
+
+      def build_summary(operation)
+        "#{operation.action.humanize} #{operation.schema_name}"
+      end
+
+      def build_operation_id(operation)
+        "#{operation.action}#{operation.schema_name}"
+      end
+
+      def build_parameters(operation, meta)
+        params = build_path_parameters(operation)
+        params += build_query_parameters(meta) if meta&._parameters
+        params
+      end
+
+      def build_path_parameters(operation)
+        operation.path_parameters.map do |param|
+          {
+            name:     param,
+            in:       "path",
+            required: true,
+            schema:   { type: "string" }
+          }
+        end
+      end
+
+      def build_query_parameters(meta)
+        meta._parameters.map do |param|
+          {
+            name:        param[:name],
+            in:          param[:in].to_s,
+            required:    param[:required] || false,
+            description: param[:description],
+            schema:      { type: param[:type].to_s }
+          }.compact
+        end
+      end
+
+      def build_default_responses(operation) # rubocop:disable Metrics/MethodLength
+        status = operation.action == "create" ? "201" : "200"
+        ref    = { "$ref" => "#/components/schemas/#{operation.schema_name}" }
+
+        responses = {
+          status => {
+            description: "#{operation.action.humanize} #{operation.schema_name}",
+            content:     {
+              "application/json" => {
+                schema: operation.action == "index" ? { type: "array", items: ref } : ref
+              }
+            }
+          }
+        }
+
+        responses["422"] = { description: "Unprocessable entity" } if operation.has_body
+        responses["404"] = { description: "Not found" }            if %w[show update destroy].include?(operation.action)
+
+        responses
+      end
+
+      def build_custom_responses(meta)
+        meta._responses.each_with_object({}) do |(status, response), hash|
+          hash[status.to_s] = build_response_object(response)
+        end
+      end
+
+      def build_response_object(response)
+        obj = { description: response[:description] }
+        return obj unless response[:schema]
+
+        obj[:content] = {
+          "application/json" => {
+            schema: resolve_schema(response[:schema])
+          }
+        }
+        obj
+      end
+
+      def resolve_schema(schema)
+        case schema
+        in { type: :array, items: Symbol => ref }
+          { type: "array", items: { "$ref" => "#/components/schemas/#{ref.to_s.classify}" } }
+        in Symbol => ref
+          { "$ref" => "#/components/schemas/#{ref.to_s.classify}" }
+        else
+          schema
+        end
+      end
+
+      def build_request_body(operation)
+        ref = { "$ref" => "#/components/schemas/#{operation.schema_name}Input" }
+
+        {
+          required: true,
+          content:  {
+            "application/json" => { schema: ref }
+          }
+        }
+      end
+
+      def operation_meta(operation)
+        openapi_class = find_openapi_class(operation)
+        openapi_class&._operations&.dig(operation.action.to_sym)
+      end
+
+      def find_openapi_class(operation)
+        openapi_name = "#{operation.schema_name}Openapi"
+        Object.const_get(openapi_name)
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/openapi_blocks/routing/operation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module OpenapiBlocks
+  module Routing
+    class Operation # rubocop:disable Style/Documentation
+      ACTIONS_MAP = {
+        "index"   => { verbs: ["get"], has_body: false },
+        "show"    => { verbs: ["get"],           has_body: false },
+        "create"  => { verbs: ["post"],          has_body: true  },
+        "update"  => { verbs: %w[put patch], has_body: true },
+        "destroy" => { verbs: ["delete"], has_body: false }
+      }.freeze
+
+      attr_reader :verbs, :path, :action, :controller, :has_body
+
+      def initialize(route)
+        @controller = route[:controller]
+        @action     = route[:action]
+        @path       = normalize_path(route[:path])
+        @verbs      = ACTIONS_MAP.dig(@action, :verbs)
+        @has_body   = ACTIONS_MAP.dig(@action, :has_body)
+      end
+
+      def valid?
+        ACTIONS_MAP.key?(@action) && @verbs.present?
+      end
+
+      def path_parameters
+        @path.scan(/\{(\w+)\}/).flatten
+      end
+
+      def schema_name
+        @controller.split("/").last.classify
+      end
+
+      private
+
+      def normalize_path(path)
+        path
+          .gsub("(.:format)", "")
+          .gsub(/:(\w+)/, '{\1}')
+      end
+    end
+  end
+end