tina4ruby 3.13.41 → 3.13.42

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74de2870c01871240bb98d6ceeb66cd5bc5bf05c6e1c4e82d19a198d585d83e6
-  data.tar.gz: 9d548edf025f53d6547216f3a421d9215eb893cfda89131c342910ebc2c820bb
+  metadata.gz: fdfe0b3f854e7ecea3419e6c10efe9e527be73952c8d570fb46106e0476255ec
+  data.tar.gz: 1c63029ec5a6e61fb91c7add6377735f6a8b740d0a416826333d400f493a623a
 SHA512:
-  metadata.gz: 3d2db7a1fc7dfcb95848dbc80c4f76664800bd6692a460667f5dfcbb59cb59fcba101737773c4eda4b4731275f735b4ef494164388869ded0849d29bb6de3804
-  data.tar.gz: 49e9c4742313a45ebb610cc5840c1b277915db9b1a5eb3a98dcb5b680a93d336b5b1d846698a9ec9121d2d722c905b8e0261b2532d050d0d7805b27a6c2c5228
+  metadata.gz: 53d20a66c7f796f36befa7777c8e62cf494ff659ef0e9d8aa7f5b7cb078c2abef4c3fc4fe99bc61df797681212d3a91bdd73bf67e6be16a4cd4da15cf91c3f02
+  data.tar.gz: 93a184a4b081ad26a81162ac08d61b4ab6051dd1ea90097dfce1dbd177610d2154dc741eb77a0ca31a3d68eb3813dfea1f99801a92550e568450cd3e9a9a2869

data/lib/tina4/swagger.rb

@@ -3,23 +3,68 @@ require "json"
 
 module Tina4
   module Swagger
+    # Process-wide registries for security schemes and reusable component
+    # schemas declared programmatically (add_security_scheme / add_schema).
+    # Kept module-level so app bootstrap can register before any generate()
+    # call; reset_registry clears them (tests).
+    @registered_schemes = {}
+    @registered_schemas = {}
+
     class << self
+      # ── Programmatic registries ────────────────────────────────────
+
+      # Register a named OpenAPI security scheme (e.g. an oauth2 scheme with
+      # scopes, or a custom apiKey). Call at app bootstrap, before generate().
+      #
+      #   Tina4::Swagger.add_security_scheme("oauth2", {
+      #     "type" => "oauth2",
+      #     "flows" => { "clientCredentials" => {
+      #       "tokenUrl" => "https://api.example.com/oauth/token",
+      #       "scopes" => { "read:users" => "Read users", "write:users" => "Write users" }
+      #     } }
+      #   })
+      def add_security_scheme(name, definition)
+        @registered_schemes[name.to_s] = definition
+      end
+
+      # Register a reusable component schema, referenceable via
+      # swagger_meta[:request_schema] / [:response_schemas] or a raw $ref.
+      def add_schema(name, schema)
+        @registered_schemas[name.to_s] = schema
+      end
+
+      # Clear the security-scheme and schema registries (test helper).
+      def reset_registry
+        @registered_schemes = {}
+        @registered_schemas = {}
+      end
+
       def generate(routes = [])
         spec = base_spec
         route_list = routes.empty? ? Tina4::Router.routes : routes
         # Accumulators shared across routes: ORM models referenced
-        # (-> components.schemas), tags used (-> top-level tags[]), seen
-        # operationIds (de-dup — OpenAPI requires them unique).
-        ctx = { models: {}, used_tags: [], seen_ids: [] }
+        # (-> components.schemas), registered custom-schema names referenced
+        # by routes, tags used (-> top-level tags[]), seen operationIds
+        # (de-dup — OpenAPI requires them unique).
+        ctx = { models: {}, ref_schemas: [], used_tags: [], seen_ids: [],
+                schemes: spec["components"]["securitySchemes"] }
         route_list.each do |route|
+          next unless included?(route.path)
+
           add_route_to_spec(spec, route, ctx)
         end
 
-        unless ctx[:models].empty?
-          spec["components"]["schemas"] = {}
+        unless ctx[:models].empty? && ctx[:ref_schemas].empty?
+          spec["components"]["schemas"] ||= {}
           ctx[:models].each do |name, klass|
             spec["components"]["schemas"][name] = model_schema(klass)
           end
+          ctx[:ref_schemas].each do |name|
+            next unless @registered_schemas.key?(name)
+            next if spec["components"]["schemas"].key?(name)
+
+            spec["components"]["schemas"][name] = @registered_schemas[name]
+          end
         end
         spec["tags"] = ctx[:used_tags].map { |t| { "name" => t } } unless ctx[:used_tags].empty?
 
@@ -63,22 +108,88 @@ module Tina4
         end
 
         {
-          "openapi" => "3.0.3",
+          "openapi" => resolve_openapi_version(ENV["TINA4_SWAGGER_OPENAPI"]),
           "info" => info,
           "servers" => servers,
           "paths" => {},
           "components" => {
-            "securitySchemes" => {
-              "bearerAuth" => {
-                "type" => "http",
-                "scheme" => "bearer",
-                "bearerFormat" => "JWT"
-              }
-            }
+            "securitySchemes" => security_schemes
           }
         }
       end
 
+      # OpenAPI version — default 3.0.3 for broad tool compatibility; opt in to
+      # 3.1.0 via TINA4_SWAGGER_OPENAPI=3.1 (the schemas this generator emits
+      # are valid in both dialects).
+      def resolve_openapi_version(val)
+        v = val.to_s.strip
+        return "3.0.3" if v.empty?
+        return "3.1.0" if %w[3.1 3.1.0].include?(v)
+        return "3.0.3" if %w[3.0 3.0.3].include?(v)
+
+        v # honour an explicit full version verbatim
+      end
+
+      # Resolve components.securitySchemes from defaults + env + registry.
+      def security_schemes
+        schemes = {
+          "bearerAuth" => {
+            "type" => "http",
+            "scheme" => "bearer",
+            # Default bearer format (the built-in bearerAuth scheme). JWT unless an
+            # API uses opaque tokens / API keys as the bearer (e.g. sk_live_...).
+            "bearerFormat" => ENV["TINA4_SWAGGER_BEARER_FORMAT"] || "JWT"
+          }
+        }
+
+        # Optional apiKey scheme — emitted as "apiKeyAuth" when a header/query
+        # name is configured (e.g. X-Api-Key).
+        api_key_name = ENV["TINA4_SWAGGER_API_KEY_NAME"]
+        if api_key_name && !api_key_name.empty?
+          api_key_in = ENV["TINA4_SWAGGER_API_KEY_IN"] || "header"
+          api_key_in = "header" unless %w[header query cookie].include?(api_key_in)
+          schemes["apiKeyAuth"] = {
+            "type" => "apiKey",
+            "name" => api_key_name,
+            "in" => api_key_in
+          }
+        end
+
+        # Registered schemes win (let an app override bearerAuth or add oauth2).
+        @registered_schemes.each { |name, defn| schemes[name] = defn }
+        schemes
+      end
+
+      # Which scheme secured routes use by default when no per-route security
+      # is declared.
+      def default_scheme
+        scheme = ENV["TINA4_SWAGGER_DEFAULT_SCHEME"]
+        scheme && !scheme.empty? ? scheme : "bearerAuth"
+      end
+
+      # Path filtering. Framework internals (/swagger, /__dev) are ALWAYS
+      # excluded; then TINA4_SWAGGER_INCLUDE (allow-list) / _EXCLUDE apply.
+      def included?(raw_path)
+        ["/swagger", "/__dev"].each do |internal|
+          return false if raw_path == internal || raw_path.start_with?("#{internal}/")
+        end
+
+        includes = csv(ENV["TINA4_SWAGGER_INCLUDE"])
+        unless includes.empty?
+          matched = includes.any? { |p| raw_path == p || raw_path.start_with?(p) }
+          return false unless matched
+        end
+
+        excludes = csv(ENV["TINA4_SWAGGER_EXCLUDE"])
+        return false if excludes.any? { |p| raw_path == p || raw_path.start_with?(p) }
+
+        true
+      end
+
+      def csv(val)
+        val.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+
       # servers[] — TINA4_SWAGGER_SERVERS (comma-separated) for a multi-server
       # list, else SWAGGER_DEV_URL, else the relative "/" default.
       def servers
@@ -124,31 +235,135 @@ module Tina4
           "description" => meta[:description] || "",
           "tags" => tags,
           "parameters" => build_parameters(route),
-          "responses" => meta[:responses] || model_or_default_responses(ref, meta[:model_list])
+          "responses" => build_responses(meta, ref, ctx)
         }
 
         operation["deprecated"] = true if meta[:deprecated]
 
-        if route.auth_handler
-          operation["security"] = [{ "bearerAuth" => [] }]
-        end
+        security = resolve_security(meta, route, ctx[:schemes])
+        operation["security"] = security unless security.nil?
 
         if %w[post put patch].include?(method)
-          operation["requestBody"] = build_request_body(method, meta, ref)
+          operation["requestBody"] = build_request_body(method, meta, ref, ctx)
         end
 
         spec["paths"][path][method] = operation
       end
 
-      def build_request_body(_method, meta, ref)
+      # Auth — explicit per-route security wins (an explicit "public"/[] = no
+      # security); otherwise a secured route gets the default scheme. Returns
+      # nil when the route declares nothing and is not secured (omit the key).
+      def resolve_security(meta, route, schemes)
+        if meta.key?(:security)
+          reqs = normalize_security(meta[:security], meta[:scopes])
+          return reqs.empty? ? [] : sanitize_security(reqs, schemes)
+        end
+
+        return sanitize_security([{ default_scheme => [] }], schemes) if route.auth_handler
+
+        nil
+      end
+
+      # Normalize swagger_meta[:security] to an OpenAPI security-requirement list.
+      #
+      #   security: "oauth2", scopes: ["read"]   -> [{"oauth2" => ["read"]}]
+      #   security: { "bearerAuth" => [] }        -> [{"bearerAuth" => []}]   (AND within one map)
+      #   security: [{"oauth2"=>["read"]}, {...}] -> verbatim (OR across maps)
+      #   security: "public" / []                 -> [] (explicitly no auth)
+      def normalize_security(value, scopes)
+        scope_list = Array(scopes).map(&:to_s)
+        if value.nil? || value == [] || (value.is_a?(String) && %w[public none].include?(value))
+          return []
+        end
+
+        case value
+        when String
+          [{ value => scope_list }]
+        when Hash
+          [value.each_with_object({}) { |(k, v), h| h[k.to_s] = Array(v).map(&:to_s) }]
+        when Array
+          value.map { |req| req.each_with_object({}) { |(k, v), h| h[k.to_s] = Array(v).map(&:to_s) } }
+        else
+          []
+        end
+      end
+
+      # Keep a security-requirement list spec-valid: scopes are allowed only on
+      # oauth2/openIdConnect schemes; everything else gets an empty array
+      # (OpenAPI requires that for http/apiKey).
+      def sanitize_security(reqs, schemes)
+        scope_ok = %w[oauth2 openIdConnect]
+        reqs.map do |req|
+          req.each_with_object({}) do |(name, scopes), clean|
+            stype = (schemes[name] || {})["type"]
+            clean[name] = scope_ok.include?(stype) ? Array(scopes) : []
+          end
+        end
+      end
+
+      def build_request_body(_method, meta, ref, ctx)
         return meta[:request_body] if meta[:request_body]
 
+        # Registered custom request schema ($ref) wins over the ORM-model ref.
+        if (req_schema = meta[:request_schema])
+          name, content_type = request_schema_parts(req_schema)
+          ctx[:ref_schemas] << name unless ctx[:ref_schemas].include?(name)
+          content = { "schema" => { "$ref" => "#/components/schemas/#{name}" } }
+          content["example"] = meta[:example] if meta[:example]
+          return { "content" => { content_type => content } }
+        end
+
         schema = ref ? { "$ref" => ref } : { "type" => "object" }
         content = { "schema" => schema }
         content["example"] = meta[:example] if meta[:example]
         { "content" => { "application/json" => content } }
       end
 
+      # swagger_meta[:request_schema] accepts "Name" or { name:, content_type: }.
+      def request_schema_parts(req_schema)
+        if req_schema.is_a?(Hash)
+          [(req_schema[:name] || req_schema["name"]).to_s,
+           (req_schema[:content_type] || req_schema["content_type"] || "application/json").to_s]
+        else
+          [req_schema.to_s, "application/json"]
+        end
+      end
+
+      def build_responses(meta, ref, ctx)
+        return meta[:responses] if meta[:responses]
+
+        responses = model_or_default_responses(ref, meta[:model_list])
+
+        # Registered response schemas ($ref) — explicit and authoritative.
+        if (resp_schemas = meta[:response_schemas])
+          resp_schemas.each do |status, spec|
+            name, is_list = response_schema_parts(spec)
+            ctx[:ref_schemas] << name unless ctx[:ref_schemas].include?(name)
+            sref = "#/components/schemas/#{name}"
+            schema = is_list ? { "type" => "array", "items" => { "$ref" => sref } } : { "$ref" => sref }
+            responses[status.to_s] = {
+              "description" => status.to_s.start_with?("2") ? "Successful response" : "Response",
+              "content" => { "application/json" => { "schema" => schema } }
+            }
+          end
+        end
+
+        responses
+      end
+
+      # A response-schema entry is "Name", { name:, list: } or [name, is_list].
+      def response_schema_parts(spec)
+        case spec
+        when Hash
+          [(spec[:name] || spec["name"]).to_s,
+           !!(spec[:list] || spec["list"] || spec[:is_list] || spec["is_list"])]
+        when Array
+          [spec[0].to_s, !!spec[1]]
+        else
+          [spec.to_s, false]
+        end
+      end
+
       def model_or_default_responses(ref, model_list)
         return default_responses unless ref
 

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.13.41"
+  VERSION = "3.13.42"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.41
+  version: 3.13.42
 platform: ruby
 authors:
 - Tina4 Team