swagger_docs_rails 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 986ca9ffc158816e3c72aea16ba3152bb5e64a545f8dd552c6bd47b921ffe261
-  data.tar.gz: 87e34cedd36d1eec79b6f3a79fb8bcea9f235914ccbf39698afec9cbcb3f425a
+  metadata.gz: ed2391636fb27b506bd380cfa91da5914c2ec8080316824ac8c7bf8f90c49df1
+  data.tar.gz: 25acbaf01c6a26adb15329144491a3deae5c4d8ff867ef62176ccdc18168db5a
 SHA512:
-  metadata.gz: 380f285a934cdbe245bf27bc3e773a037cdb141c6008b3801b3caf6071f205640f06e409bc9ecaf2795df5ce1dec160931f9e97403139d06c13f2c004f0308da
-  data.tar.gz: d57f458c87aca534f58b926dc2e71eb651e97c54438ddbff035d91da614959f4c36016bdb93aa6c1987097d8568e47beffc96e4c233e3904ba6253088fc3270d
+  metadata.gz: a01043004ed6d611756e6e28d3f68dc33a23d67bba4287aa7fb5156ebb162ad460f1bd426d962c4e1cb66f7fb87ad4a3ada7e2e9451b6dbcaf2f03164628141e
+  data.tar.gz: 473408951994dc9cf74ae75345eed034c6f85de8978084066ef699ebf3e2d8a76d1f5ff67a9fb5be7508a59554e24488f08a931b688a235f5537d0bd59db99e0

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.0
+
+- Esquemas de segurança configuráveis (`security_schemes` e `global_security`).
+- Suporte a autenticação Bearer JWT e API Key (header ou query) no OpenAPI e Swagger UI.
+- Template de install e README atualizados com exemplos de `Authorize`.
+
+## 0.1.2
+
+- Atualiza os metadados de autoria da gem para Ordex Sistemas.
+
 ## 0.1.1
 
 - Atualização de metadados para nova publicação da gem.

data/MIT-LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Clic API
+Copyright (c) 2026 Ordex sistemas
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -47,9 +47,36 @@ SwaggerDocsRails.configure do |config|
   config.password = ENV.fetch("SWAGGER_PASSWORD", "")
   config.additional_controller_paths = []
   config.output_path = Rails.root.join("public", "swagger", "openapi.json")
+
+  # Autenticação no Swagger UI (botão Authorize)
+  config.security_schemes = [
+    { name: "BearerAuth", type: :http, scheme: "bearer", bearer_format: "JWT",
+      description: "Token JWT" },
+    { name: "ApiKeyAuth", type: :api_key, in: "header", param_name: "X-Api-Key",
+      description: "Chave interna da API" }
+  ]
+  config.global_security = [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
 end
 ```
 
+### Autenticação (Bearer, API Key)
+
+A gem gera `components.securitySchemes` e `security` global a partir da configuração.
+No Swagger UI, use **Authorize** para informar JWT ou API Key; `persistAuthorization` mantém os valores na sessão.
+
+Tipos suportados em `security_schemes`:
+
+| `type`     | Campos principais                                      |
+|-----------|---------------------------------------------------------|
+| `:http`   | `scheme`, `bearer_format`, `description`                |
+| `:api_key`| `param_name` (ou `header_name`), `in` (`header`/`query`) |
+
+`global_security` define quais esquemas exigir. Vários hashes em sequência = **OR** (Bearer **ou** ApiKey):
+
+```ruby
+config.global_security = [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
+```
+
 ## Uso
 
 Gere o arquivo OpenAPI:

data/app/controllers/swagger_docs_rails/swagger_controller.rb

@@ -62,12 +62,7 @@ module SwaggerDocsRails
 
     def build_doc(server_url)
       if configuracao.live_reload || self.class.cached_doc.nil?
-        config = {
-          title: configuracao.title,
-          version: configuracao.version,
-          description: configuracao.description,
-          server_url: server_url
-        }
+        config = configuracao.to_generator_config.merge(server_url: server_url)
 
         document = SwaggerDocsRails::Generator.new(config: config).generate
         self.class.cached_doc = JSON.generate(document)

data/lib/generators/swagger_docs_rails/install/templates/swagger_docs_rails.rb

@@ -11,4 +11,28 @@ SwaggerDocsRails.configure do |config|
   config.password = ENV.fetch("SWAGGER_PASSWORD", "")
   config.additional_controller_paths = []
   config.output_path = Rails.root.join("public", "swagger", "openapi.json")
+
+  # Autenticação documentada no Swagger UI (botão "Authorize")
+  config.security_schemes = [
+    {
+      name: "BearerAuth",
+      type: :http,
+      scheme: "bearer",
+      bearer_format: "JWT",
+      description: "Token JWT (Authorization: Bearer <token>)"
+    },
+    {
+      name: "ApiKeyAuth",
+      type: :api_key,
+      in: "header",
+      param_name: "X-Api-Key",
+      description: "Chave interna da API"
+    }
+  ]
+
+  # OR: qualquer um dos esquemas acima satisfaz a segurança global
+  config.global_security = [
+    { BearerAuth: [] },
+    { ApiKeyAuth: [] }
+  ]
 end

data/lib/swagger_docs_rails/configuration.rb

@@ -4,7 +4,8 @@ module SwaggerDocsRails
   class Configuration
     attr_accessor :enabled, :title, :version, :description,
                   :server_url, :live_reload, :username, :password,
-                  :additional_controller_paths, :output_path
+                  :additional_controller_paths, :output_path,
+                  :security_schemes, :global_security
 
     def initialize
       @enabled = !Rails.env.production?
@@ -17,6 +18,39 @@ module SwaggerDocsRails
       @password = ENV.fetch("SWAGGER_PASSWORD", "")
       @additional_controller_paths = []
       @output_path = Rails.root.join("public", "swagger", "openapi.json")
+      @security_schemes = esquemas_seguranca_padrao
+      @global_security = [{ BearerAuth: [] }]
+    end
+
+    def esquemas_seguranca_padrao
+      [
+        {
+          name: "BearerAuth",
+          type: :http,
+          scheme: "bearer",
+          bearer_format: "JWT",
+          description: "Token JWT (header Authorization: Bearer <token>)"
+        }
+      ]
+    end
+
+    def openapi_security_schemes
+      SecuritySchemeBuilder.build_all(security_schemes)
+    end
+
+    def openapi_global_security
+      SecuritySchemeBuilder.build_global_security(global_security)
+    end
+
+    def to_generator_config
+      {
+        title: title,
+        version: version,
+        description: description,
+        server_url: server_url,
+        security_schemes: openapi_security_schemes,
+        global_security: openapi_global_security
+      }
     end
   end
 end

data/lib/swagger_docs_rails/openapi_builder.rb

@@ -74,7 +74,7 @@ module SwaggerDocsRails
         tags:       build_tags(versions),
         paths:      paths,
         components: components,
-        security:   [{ BearerAuth: [] }]
+        security:   build_global_security
       }
     end
 
@@ -599,14 +599,21 @@ module SwaggerDocsRails
       }
     end
 
+    def build_global_security
+      requisitos = @config[:global_security]
+      return requisitos if requisitos.present?
+
+      esquemas = @config[:security_schemes]
+      if esquemas.is_a?(Hash) && esquemas.any?
+        esquemas.keys.map { |nome| { nome.to_s => [] } }
+      else
+        [{ "BearerAuth" => [] }]
+      end
+    end
+
     def build_components
       {
-        securitySchemes: {
-          BearerAuth: {
-            type: "http", scheme: "bearer", bearerFormat: "JWT",
-            description: "Token JWT obtido em /api/v1/auth/login"
-          }
-        },
+        securitySchemes: build_security_schemes,
         schemas: @schema_parser.to_openapi_schemas
                                .merge(@dynamic_schemas)
                                .merge(shared_schemas),
@@ -624,6 +631,18 @@ module SwaggerDocsRails
       }
     end
 
+    def build_security_schemes
+      esquemas = @config[:security_schemes]
+      return esquemas if esquemas.is_a?(Hash) && esquemas.any?
+
+      {
+        "BearerAuth" => {
+          type: "http", scheme: "bearer", bearerFormat: "JWT",
+          description: "Token JWT (header Authorization: Bearer <token>)"
+        }
+      }
+    end
+
     def schema_exists?(schema_name)
       return true if %w[Error ValidationError GenericResponse GenericInput].include?(schema_name)
       return true if @dynamic_schemas.key?(schema_name)

data/lib/swagger_docs_rails/security_scheme_builder.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SwaggerDocsRails
+  module SecuritySchemeBuilder
+    module_function
+
+    def to_openapi(scheme)
+      tipo = scheme[:type].to_s.downcase.tr("-", "_").to_sym
+
+      case tipo
+      when :http, :bearer
+        http_scheme(scheme)
+      when :api_key, :apikey
+        api_key_scheme(scheme)
+      else
+        raise ArgumentError, "Tipo de segurança não suportado: #{scheme[:type]} (use :http ou :api_key)"
+      end
+    end
+
+    def build_all(schemes)
+      Array(schemes).each_with_object({}) do |scheme, resultado|
+        nome = scheme[:name] || scheme["name"]
+        raise ArgumentError, "security_schemes: :name é obrigatório" if nome.nil? || nome.to_s.strip.empty?
+
+        resultado[nome.to_s] = to_openapi(scheme)
+      end
+    end
+
+    def build_global_security(requirements)
+      Array(requirements).map do |requisito|
+        requisito.each_with_object({}) do |(nome, escopos), hash|
+          hash[nome.to_s] = Array(escopos)
+        end
+      end
+    end
+
+    def http_scheme(scheme)
+      {
+        type: "http",
+        scheme: scheme[:scheme].presence || "bearer",
+        bearerFormat: scheme[:bearer_format].presence || scheme[:bearerFormat].presence || "JWT",
+        description: scheme[:description].presence || "Token Bearer"
+      }.compact
+    end
+
+    def api_key_scheme(scheme)
+      local = scheme[:in].presence || scheme[:location].presence || "header"
+      nome_param = scheme[:param_name].presence || scheme[:header_name].presence ||
+                   scheme[:name_param].presence
+      if nome_param.nil? || nome_param.to_s.strip.empty?
+        raise ArgumentError, "security_schemes api_key: informe :param_name ou :header_name"
+      end
+
+      {
+        type: "apiKey",
+        in: local.to_s,
+        name: nome_param,
+        description: scheme[:description].presence || "Chave de API"
+      }.compact
+    end
+  end
+end

data/lib/swagger_docs_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwaggerDocsRails
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/swagger_docs_rails.rb

@@ -4,6 +4,7 @@ require "json"
 require "fileutils"
 require "swagger_docs_rails/version"
 require "swagger_docs_rails/configuration"
+require "swagger_docs_rails/security_scheme_builder"
 require "swagger_docs_rails/schema_parser"
 require "swagger_docs_rails/controller_parser"
 require "swagger_docs_rails/openapi_builder"

data/lib/tasks/swagger_docs_rails.rake

@@ -15,12 +15,12 @@ namespace :swagger do
       "API"
     end
 
-    dados_configuracao = {
+    dados_configuracao = config.to_generator_config.merge(
       title: ENV.fetch("SWAGGER_TITLE", config.title || app_name),
       version: ENV.fetch("SWAGGER_VERSION", config.version || "1.0.0"),
       description: ENV.fetch("SWAGGER_DESC", config.description || "Documentação OpenAPI gerada automaticamente"),
       server_url: ENV.fetch("SWAGGER_SERVER", config.server_url || "/")
-    }
+    )
 
     puts "→ Parsing db/schema.rb..."
     schema_parser = SwaggerDocsRails::SchemaParser.new

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: swagger_docs_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
-- Clic API
+- ordex sistemas
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -32,7 +32,7 @@ dependencies:
 description: Rails Engine para gerar documentação OpenAPI 3.0 a partir do schema.rb
   e controllers Rails.
 email:
-- dev@clic.com.br
+- ordexsistemas@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -51,6 +51,7 @@ files:
 - lib/swagger_docs_rails/generator.rb
 - lib/swagger_docs_rails/openapi_builder.rb
 - lib/swagger_docs_rails/schema_parser.rb
+- lib/swagger_docs_rails/security_scheme_builder.rb
 - lib/swagger_docs_rails/version.rb
 - lib/tasks/swagger_docs_rails.rake
 homepage: https://rubygems.org/gems/swagger_docs_rails