swagger_docs_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 44980ee6b53ffdfe7cfa48ee2f6226255f5e310a59d64898ae6296fa0b9613d4
+  data.tar.gz: dac2a21c73832ec25dd4e06cd0ec0ed312f337a601d9757b46a32ac72bb5eadf
+SHA512:
+  metadata.gz: bc22c1ad42adc28b3b172d46aefdedcb40b3a5a9103a5a27aa2c1be2a97a71807026fa5beb72b102d008e918fb6742a0827e716413414e423e9c4698f64fa7fa
+  data.tar.gz: a7208d0e7729930892d1032f65a842be201e36c5089efeef6fba07a79d5a08d2f5b18edefc5ac2ce21ada1092fde7e48d1843d07851849688a89110d615755f4

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Primeira versão da gem `swagger_docs_rails`.
+- Geração de OpenAPI 3.0 a partir de `db/schema.rb` e controllers Rails.
+- Swagger UI via Rails Engine.
+- Tasks `swagger:generate` e `swagger:validate`.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clic API
+
+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.

data/README.md

@@ -0,0 +1,71 @@
+# Swagger Docs Rails
+
+Gem Rails Engine para gerar documentação OpenAPI 3.0 a partir do `db/schema.rb`, controllers Rails e rotas da aplicação.
+
+## Instalação
+
+Adicione ao `Gemfile` da API:
+
+```ruby
+gem "swagger_docs_rails"
+```
+
+Para desenvolvimento local:
+
+```ruby
+gem "swagger_docs_rails", path: "../swagger_docs_rails"
+```
+
+Execute:
+
+```bash
+bundle install
+rails generate swagger_docs_rails:install
+```
+
+Adicione as rotas:
+
+```ruby
+if ENV["ENABLE_SWAGGER"] == "true"
+  mount SwaggerDocsRails::Engine => "/"
+end
+```
+
+## Configuração
+
+O generator cria `config/initializers/swagger_docs_rails.rb`:
+
+```ruby
+SwaggerDocsRails.configure do |config|
+  config.enabled = !Rails.env.production?
+  config.title = Rails.application.class.module_parent_name
+  config.version = "1.0.0"
+  config.description = "Documentação OpenAPI gerada automaticamente"
+  config.server_url = ENV.fetch("HOST_URL", "/")
+  config.live_reload = Rails.env.development?
+  config.username = ENV.fetch("SWAGGER_USER", "admin")
+  config.password = ENV.fetch("SWAGGER_PASSWORD", "")
+  config.additional_controller_paths = []
+  config.output_path = Rails.root.join("public", "swagger", "openapi.json")
+end
+```
+
+## Uso
+
+Gere o arquivo OpenAPI:
+
+```bash
+rails swagger:generate
+```
+
+Valide o arquivo gerado, se a aplicação possuir `openapi_parser`:
+
+```bash
+rails swagger:validate
+```
+
+Com `ENABLE_SWAGGER=true`, acesse:
+
+- `/swagger`
+- `/swagger/doc`
+- `/swagger/cache` com método `DELETE`

data/app/controllers/swagger_docs_rails/swagger_controller.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module SwaggerDocsRails
+  class SwaggerController < ActionController::Base
+    SWAGGER_UI_CDN = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5"
+
+    before_action :authenticate_swagger!
+
+    def ui
+      render html: html_page.html_safe, layout: false
+    end
+
+    def doc
+      render json: JSON.parse(build_doc(resolved_server_url))
+    end
+
+    def reset
+      self.class.cached_doc = nil
+      render json: { message: "Cache do Swagger limpo. Acesse /swagger para regenerar." }, status: :ok
+    end
+
+    class << self
+      attr_accessor :cached_doc
+    end
+
+    private
+
+    def authenticate_swagger!
+      return true if swagger_username.blank? && swagger_password.blank?
+
+      authenticate_or_request_with_http_basic("Swagger API Docs") do |user, password|
+        user_ok = ActiveSupport::SecurityUtils.secure_compare(user.to_s, swagger_username)
+        password_ok = ActiveSupport::SecurityUtils.secure_compare(password.to_s, swagger_password)
+        user_ok && password_ok
+      end
+    end
+
+    def swagger_username
+      configuracao.username.to_s
+    end
+
+    def swagger_password
+      configuracao.password.to_s
+    end
+
+    def configuracao
+      SwaggerDocsRails.configuration
+    end
+
+    def resolved_server_url
+      configured = configuracao.server_url.to_s.strip
+      if configured.start_with?("http://", "https://")
+        configured.chomp("/")
+      else
+        request.base_url.chomp("/")
+      end
+    end
+
+    def doc_url
+      "#{request.base_url}/swagger/doc"
+    end
+
+    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
+        }
+
+        document = SwaggerDocsRails::Generator.new(config: config).generate
+        self.class.cached_doc = JSON.generate(document)
+
+        output = configuracao.output_path
+        FileUtils.mkdir_p(File.dirname(output.to_s))
+        File.write(output.to_s, JSON.pretty_generate(document))
+      end
+
+      update_server_url_in_doc(server_url)
+    end
+
+    def update_server_url_in_doc(server_url)
+      doc = JSON.parse(self.class.cached_doc)
+      doc["servers"] = [{ "url" => server_url, "description" => "Servidor da API" }]
+      JSON.generate(doc)
+    end
+
+    def html_page
+      cdn = SWAGGER_UI_CDN
+      title = configuracao.title
+      absolute_doc_url = doc_url
+      gem_version = SwaggerDocsRails::VERSION
+
+      <<~HTML
+        <!DOCTYPE html>
+        <html lang="pt-BR">
+        <head>
+          <meta charset="UTF-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1" />
+          <title>#{title} - Documentação da API</title>
+          <link rel="stylesheet" href="#{cdn}/swagger-ui.css" />
+          <style>
+            * { box-sizing: border-box; }
+            body { margin: 0; background: #f5f7fa; font-family: sans-serif; }
+            .topbar { display: none !important; }
+            #swagger-ui { max-width: 1400px; margin: 0 auto; padding: 1.5rem 1rem; }
+            #swagger-regen-bar {
+              background: #1b1b1b; color: #fff; padding: 8px 16px;
+              display: flex; align-items: center; gap: 12px; font-size: 13px;
+            }
+            #swagger-regen-bar strong { font-size: 14px; }
+            #swagger-gem-version {
+              background: #2f3b52; border-radius: 999px; color: #dce8ff;
+              font-size: 12px; font-weight: 600; padding: 4px 10px;
+            }
+            #btn-regen {
+              background: #4CAF50; color: white; border: none; border-radius: 4px;
+              padding: 5px 14px; cursor: pointer; font-size: 13px; font-weight: 600;
+            }
+            #btn-regen:hover { background: #45a049; }
+            #btn-regen.loading { background: #888; cursor: default; }
+            #regen-status { font-style: italic; color: #aef; }
+          </style>
+        </head>
+        <body>
+          <div id="swagger-regen-bar">
+            <strong>#{title}</strong>
+            <span id="swagger-gem-version">swagger_docs_rails v#{gem_version}</span>
+            <button id="btn-regen" onclick="regenSwagger()">Regenerar documentação</button>
+            <span id="regen-status"></span>
+          </div>
+          <div id="swagger-ui"></div>
+          <script src="#{cdn}/swagger-ui-bundle.js"></script>
+          <script src="#{cdn}/swagger-ui-standalone-preset.js"></script>
+          <script>
+            function regenSwagger() {
+              const btn = document.getElementById('btn-regen');
+              const status = document.getElementById('regen-status');
+              btn.classList.add('loading');
+              btn.disabled = true;
+              status.textContent = 'Limpando cache...';
+
+              fetch('/swagger/cache', { method: 'DELETE' })
+                .then(() => {
+                  status.textContent = 'Regenerando...';
+                  return fetch('#{absolute_doc_url}');
+                })
+                .then(() => {
+                  status.textContent = 'Recarregando UI...';
+                  setTimeout(() => window.location.reload(), 300);
+                })
+                .catch(() => {
+                  status.textContent = 'Erro ao regenerar.';
+                  btn.classList.remove('loading');
+                  btn.disabled = false;
+                });
+            }
+
+            window.onload = () => {
+              const CaseInsensitiveFilterPlugin = () => ({
+                fn: {
+                  opsFilter: (taggedOps, phrase) => {
+                    if (!phrase || phrase.trim() === "") return taggedOps;
+                    const q = phrase.toLowerCase().trim();
+                    return taggedOps
+                      .filter((tagObj) => {
+                        const tag = (tagObj.get("tagDetails")?.get("name") || "").toLowerCase();
+                        if (tag.includes(q)) return true;
+                        const ops = tagObj.get("operations");
+                        return ops?.some((op) => {
+                          const path = (op.get("path") || "").toLowerCase();
+                          const method = (op.get("method") || "").toLowerCase();
+                          const summary = (op.getIn(["operation", "summary"]) || "").toLowerCase();
+                          const opId = (op.getIn(["operation", "operationId"]) || "").toLowerCase();
+                          const desc = (op.getIn(["operation", "description"]) || "").toLowerCase();
+                          return path.includes(q) || method.includes(q) ||
+                                 summary.includes(q) || opId.includes(q) || desc.includes(q);
+                        });
+                      })
+                      .map((tagObj) => {
+                        const ops = tagObj.get("operations");
+                        if (!ops) return tagObj;
+                        const filtered = ops.filter((op) => {
+                          const tag = (tagObj.get("tagDetails")?.get("name") || "").toLowerCase();
+                          if (tag.includes(q)) return true;
+                          const path = (op.get("path") || "").toLowerCase();
+                          const method = (op.get("method") || "").toLowerCase();
+                          const summary = (op.getIn(["operation", "summary"]) || "").toLowerCase();
+                          const opId = (op.getIn(["operation", "operationId"]) || "").toLowerCase();
+                          const desc = (op.getIn(["operation", "description"]) || "").toLowerCase();
+                          return path.includes(q) || method.includes(q) ||
+                                 summary.includes(q) || opId.includes(q) || desc.includes(q);
+                        });
+                        return tagObj.set("operations", filtered);
+                      });
+                  }
+                }
+              });
+
+              SwaggerUIBundle({
+                url: "#{absolute_doc_url}",
+                dom_id: "#swagger-ui",
+                deepLinking: true,
+                presets: [
+                  SwaggerUIBundle.presets.apis,
+                  SwaggerUIStandalonePreset
+                ],
+                plugins: [
+                  SwaggerUIBundle.plugins.DownloadUrl,
+                  CaseInsensitiveFilterPlugin
+                ],
+                layout: "StandaloneLayout",
+                defaultModelsExpandDepth: 1,
+                defaultModelExpandDepth: 2,
+                displayRequestDuration: true,
+                filter: true,
+                tryItOutEnabled: true,
+                persistAuthorization: true
+              });
+            };
+          </script>
+        </body>
+        </html>
+      HTML
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+SwaggerDocsRails::Engine.routes.draw do
+  get "/swagger", to: "swagger#ui", as: :swagger_ui
+  get "/swagger/doc", to: "swagger#doc", as: :swagger_doc
+  delete "/swagger/cache", to: "swagger#reset", as: :swagger_reset
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module SwaggerDocsRails
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def copiar_initializer
+        template "swagger_docs_rails.rb", "config/initializers/swagger_docs_rails.rb"
+      end
+
+      def exibir_rota
+        say "Adicione ao config/routes.rb:", :green
+        say ""
+        say "if ENV[\"ENABLE_SWAGGER\"] == \"true\""
+        say "  mount SwaggerDocsRails::Engine => \"/\""
+        say "end"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+SwaggerDocsRails.configure do |config|
+  config.enabled = !Rails.env.production?
+  config.title = Rails.application.class.module_parent_name
+  config.version = "1.0.0"
+  config.description = "Documentação OpenAPI gerada automaticamente"
+  config.server_url = ENV.fetch("HOST_URL", "/")
+  config.live_reload = Rails.env.development?
+  config.username = ENV.fetch("SWAGGER_USER", "admin")
+  config.password = ENV.fetch("SWAGGER_PASSWORD", "")
+  config.additional_controller_paths = []
+  config.output_path = Rails.root.join("public", "swagger", "openapi.json")
+end

data/lib/swagger_docs_rails/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SwaggerDocsRails
+  class Configuration
+    attr_accessor :enabled, :title, :version, :description,
+                  :server_url, :live_reload, :username, :password,
+                  :additional_controller_paths, :output_path
+
+    def initialize
+      @enabled = !Rails.env.production?
+      @title = Rails.application.class.module_parent_name
+      @version = "1.0.0"
+      @description = "Documentação OpenAPI gerada automaticamente"
+      @server_url = ENV.fetch("HOST_URL", "/")
+      @live_reload = Rails.env.development?
+      @username = ENV.fetch("SWAGGER_USER", "admin")
+      @password = ENV.fetch("SWAGGER_PASSWORD", "")
+      @additional_controller_paths = []
+      @output_path = Rails.root.join("public", "swagger", "openapi.json")
+    end
+  end
+end