oas_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7eb785a5d2e4c2bf2ab00931fded8770c0f162b21dee065c9770f159f0ddd86d
+  data.tar.gz: 2ce8852c11a5f9d2e6263bc7f067e12e83029a9f87aeefc6912884f0c5912408
+SHA512:
+  metadata.gz: 8a869a622b0cc9dc8710e665b70732d9993b16dce77ebae9529c73be10e794cb5a1820213dcca99380d05e810df04e00eb2ba6e11c5457c0ec76b9b82c7a740e
+  data.tar.gz: 515c5e3a66de74241ec303dfe276104d86bee128d0cc790d40a3dcff8534dcb3dbf7d283201bffd0b4089d30b03fc90f567d512714663f6dd0d39535bae0ae92

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright a-chacon
+
+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,147 @@
+# Open API Specification For Rails
+
+OasRails is a Rails engine for generating **automatic interactive documentation for your Rails APIs**. It generates an **OAS 3.1** document and displays it using **[RapiDoc](https://rapidocweb.com)**.
+
+## Related Projects
+
+- **[ApiPie](https://github.com/Apipie/apipie-rails)**: Doesn't support OAS 3.1, requires learning a DSL, lacks a nice UI
+- **[swagger_yard-rails](https://github.com/livingsocial/swagger_yard-rails)**: Seems abandoned, but serves as inspiration
+- **[Rswag](https://github.com/rswag/rswag)**: Not automatic, depends on RSpec; Many developers now use Minitest as it's the default test framework
+- **[grape-swagger](https://github.com/ruby-grape/grape-swagger)**: Requires Grape
+- **[rspec_api_documentation](https://github.com/zipmark/rspec_api_documentation)**: Requires RSpec and a command to generate the docs
+
+## What Sets OasRails Apart?
+
+- **Dynamic**: No command required to generate docs
+- **Simple**: Complement default documentation with a few comments; no need to learn a complex DSL
+- **Pure Ruby on Rails APIs**: No additional frameworks needed (e.g., Grape, RSpec)
+
+## Motivation
+
+After experiencing the interactive documentation in Python's fast-api framework, I sought similar functionality in Ruby on Rails. Unable to find a suitable solution, I [asked on Stack Overflow](https://stackoverflow.com/questions/71947018/is-there-a-way-to-generate-an-interactive-documentation-for-rails-apis) years ago. Now, with some free time while freelancing as an API developer, I decided to build my own tool.
+
+**Note**: This is not yet a production-ready solution. The code may be rough and behave unexpectedly, but I am actively working on improving it. If you like the idea, please consider contributing to its development.
+
+The goal is to minimize the effort required to create comprehensive documentation. By following REST principles in Rails, we believe this is achievable. You can enhance the documentation using [Yard](https://yardoc.org/) tags.
+
+## Installation
+
+1. Add this line to your Rails application's Gemfile:
+
+   ```ruby
+   gem "oas_rails"`
+   ```
+
+2. Execute:
+
+```bash
+bundle
+```
+
+3. Mount the engine in your config/routes.rb file
+
+```ruby
+mount OasRails::Engine => '/docs'
+```
+
+You'll now have **basic documentation** based on your routes and automatically gathered information at `localhost:3000/docs`. To enhance it, create an initializer file and add [Yard](https://yardoc.org/) tags to your controller methods.
+
+## Usage
+
+### Initializer File
+
+You can easy create the initializer file with:
+
+```
+rails generate oas_rails:config
+```
+
+Then complete the created file with your data.
+
+**Almost every description in a OAS file support simple markdown**
+
+## Documenting Your Endpoints
+
+Almost every description in an OAS file supports simple markdown. The following tags are available for documenting your endpoints:
+
+### @summary
+
+**Structure**: `@summary text`
+
+Used to add a summary to the endpoint. It replaces the default summary/title of the endpoint.
+
+**Example**:
+`# @summary This endpoint creates a User`
+
+### @parameter
+
+**Structure**: `@parameter name(position) [type] text`
+
+Represents a parameter for the endpoint. The position can be: `header`, `path`, `cookie`, or `query`. The type should be a valid Ruby class: `String`, `Integer`, `Array<String>`, etc. Add a `!` after the class to indicate a required parameter.
+
+**Examples**:
+`# @parameter page(query) [Integer] The page number.`
+`# @parameter slug(path) [String!] Slug of the Project.`
+
+### @request_body
+
+**Structure**: `@request_body text [type] structure`
+
+Documents the request body needed by the endpoint. The structure is optional if you provide a valid Active Record class. Use `!` to indicate a required request body.
+
+**Example**:
+`# @request_body The user to be created [Hash] {user: {name: String, age: Integer, password: String}}`
+
+### @request_body_example
+
+**Structure**: `@request_body_example text [type] structure`
+
+Adds examples to the provided request body.
+
+**Example**:
+`# @request_body_example A complete User. [Hash] {user: {name: 'Luis', age: 30, password: 'MyWeakPassword123'}}`
+
+### @response
+
+**Structure**: `@response text(code) [type] structure`
+
+Documents the responses of the endpoint and overrides the default responses found by the engine.
+
+**Example**:
+`# @response User not found by the provided Id(404) [Hash] {success: Boolean, message: String}`
+
+### @tag
+
+**Structure**: `@tag text`
+
+Tags your endpoints. You can complete the tag documentation in the initializer file by defining these tags beforehand. It's not necessary for the tag to exist in your initializer file before use.
+
+**Example**:
+`# @tag Users`
+
+You can use these tags in your controller methods to enhance the automatically generated documentation. Remember to use markdown formatting in your descriptions for better readability in the generated OAS document.
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+### Roadmap and Ideas for Improvement
+
+- Clean, document and structure the code
+- Support documentation of authentication methods
+- Define Global Tags/Configuration (e.g., common responses like 404 errors)
+- Post-process the JSON and replace common objects with references to components
+- Create a temporary file with the JSON in production mode to avoid rebuilding it on every request
+- Create tags for popular gems used in APIs (e.g., a `@pagy` tag for common pagination parameters)
+- Add basic authentication to OAS and UI for security reasons
+- Implement ability to define OAS by namespaces (e.g., generate OAS for specific routes like `/api` or separate versions V1 and V2)
+
+## License
+
+The gem is available as open source under the terms of the [GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.en.html#license-text).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/config/oas_rails_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/oas_rails .css

data/app/assets/stylesheets/oas_rails/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/oas_rails/application_controller.rb

@@ -0,0 +1,4 @@
+module OasRails
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/oas_rails/oas_rails_controller.rb

@@ -0,0 +1,9 @@
+module OasRails
+  class OasRailsController < ApplicationController
+    def index; end
+
+    def oas
+      render json: Specification.new.to_json, status: :ok
+    end
+  end
+end

data/app/helpers/oas_rails/application_helper.rb

@@ -0,0 +1,4 @@
+module OasRails
+  module ApplicationHelper
+  end
+end

data/app/helpers/oas_rails/oas_rails_helper.rb

@@ -0,0 +1,4 @@
+module OasRails
+  module OasRailsHelper
+  end
+end

data/app/helpers/oas_rails/test_helper.rb

@@ -0,0 +1,4 @@
+module OasRails
+  module TestHelper
+  end
+end

data/app/jobs/oas_rails/application_job.rb

@@ -0,0 +1,4 @@
+module OasRails
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/oas_rails/application_mailer.rb

@@ -0,0 +1,6 @@
+module OasRails
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/oas_rails/application_record.rb

@@ -0,0 +1,5 @@
+module OasRails
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/views/layouts/oas_rails/application.html.erb

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Oas rails</title>
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <meta charset="utf-8">
+    <!-- Important: rapi-doc uses utf8 characters -->
+    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
+
+    <%= stylesheet_link_tag "oas_rails/application", media: "all" %>
+  </head>
+  <body>
+
+    <%= yield %>
+
+  </body>
+</html>

data/app/views/oas_rails/oas_rails/index.html.erb

@@ -0,0 +1 @@
+<rapi-doc spec-url = "<%= main_app.oas_rails_path %>/oas" theme = "dark" text-color="#f9f9f9" show-header = 'false'> </rapi-doc>

data/app/views/oas_rails/test/show.html.erb

@@ -0,0 +1 @@
+<%= @routes %>

data/config/routes.rb

@@ -0,0 +1,4 @@
+OasRails::Engine.routes.draw do
+  root 'oas_rails#index'
+  get '/oas', to: 'oas_rails#oas'
+end

data/lib/generators/oas_rails/config/config_generator.rb

@@ -0,0 +1,11 @@
+module OasRails
+  module Generators
+    class ConfigGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def copy_initializer_file
+        template "oas_rails_initializer.rb", "config/initializers/oas_rails.rb"
+      end
+    end
+  end
+end

data/lib/generators/oas_rails/config/templates/oas_rails_initializer.rb

@@ -0,0 +1,49 @@
+# config/initializers/oas_rails.rb
+OasRails.configure do |config|
+  config.info.title = 'OasRails'
+  config.info.summary = 'OasRails: Automatic Interactive API Documentation for Rails'
+  config.info.description = <<~HEREDOC
+    # Welcome to OasRails
+
+    OasRails automatically generates interactive documentation for your Rails APIs using the OpenAPI Specification 3.1 (OAS 3.1) and displays it with a nice UI.
+
+    ## Getting Started
+
+    You've successfully mounted the OasRails engine. This default documentation is based on your routes and automatically gathered information.
+
+    ## Enhancing Your Documentation
+
+    To customize and enrich your API documentation:
+
+    1. Generate an initializer file:
+
+      ```
+      rails generate oas_rails:config
+      ```
+    2. Edit the created `config/initializers/oas_rails.rb` file to override default settings and add project-specific information.
+
+    3. Use Yard tags in your controller methods to provide detailed API endpoint descriptions.
+
+    ## Features
+
+    - Automatic OAS 3.1 document generation
+    - [RapiDoc](https://github.com/rapi-doc/RapiDoc) integration for interactive exploration
+    - Minimal setup required for basic documentation
+    - Extensible through configuration and Yard tags
+
+    Explore your API documentation and enjoy the power of OasRails!
+
+    For more information and advanced usage, visit the [OasRails GitHub repository](https://github.com/a-chacon/oas_rails).
+
+
+  HEREDOC
+  config.info.contact.name = 'a-chacon'
+  config.info.contact.email = 'andres.ch@proton.me'
+  config.info.contact.url = 'https://a-chacon.com'
+  config.servers = [{ url: 'http://localhost:3000', description: 'Local' }]
+  config.tags = [{ name: "Users", description: "Manage the `amazing` Users table." }]
+
+  # config.default_tags_from = :namespace # Could be: :namespace or :controller
+  # config.request_body_automatically = true # Try to get request body for create and update methos based on the controller name.
+  # config.autodiscover_responses = true # Looks for renders in your source code and try to generate the responses.
+end

data/lib/oas_rails/configuration.rb

@@ -0,0 +1,28 @@
+module OasRails
+  class Configuration
+    attr_accessor :info, :default_tags_from, :request_body_automatically, :autodiscover_responses
+    attr_reader :servers, :tags
+
+    def initialize(**kwargs)
+      @info = Info.new
+      @servers = kwargs[:servers] || default_servers
+      @tags = []
+      @swagger_version = '3.1.0'
+      @default_tags_from = "namespace"
+      @request_body_automatically = true
+      @autodiscover_responses = true
+    end
+
+    def default_servers
+      [Server.new(url: "http://localhost:3000", description: "Rails Default Development Server")]
+    end
+
+    def servers=(value)
+      @servers = value.map { |s| Server.new(url: s[:url], description: s[:description]) }
+    end
+
+    def tags=(value)
+      @tags = value.map { |t| Tag.new(name: t[:name], description: t[:description]) }
+    end
+  end
+end

data/lib/oas_rails/contact.rb

@@ -0,0 +1,12 @@
+module OasRails
+  class Contact < OasBase
+    attr_accessor :name, :url, :email
+
+    def initialize(**kwargs)
+      super()
+      @name = kwargs[:name] || ''
+      @url = kwargs[:url] || ''
+      @email = kwargs[:email] || ''
+    end
+  end
+end

data/lib/oas_rails/engine.rb

@@ -0,0 +1,5 @@
+module OasRails
+  class Engine < ::Rails::Engine
+    isolate_namespace OasRails
+  end
+end

data/lib/oas_rails/info.rb

@@ -0,0 +1,60 @@
+module OasRails
+  class Info < OasBase
+    attr_accessor :title, :summary, :description, :terms_of_service, :contact, :license, :version
+
+    def initialize(**kwargs)
+      super()
+      @title = kwargs[:title] || default_title
+      @summary = kwargs[:summary] || default_summary
+      @description = kwargs[:description] || default_description
+      @terms_of_service = kwargs[:terms_of_service] || ''
+      @contact = Contact.new
+      @license = License.new
+      @version = kwargs[:version] || '0.0.1'
+    end
+
+    def default_title
+      "OasRails #{VERSION}"
+    end
+
+    def default_summary
+      "OasRails: Automatic Interactive API Documentation for Rails"
+    end
+
+    def default_description
+      "# Welcome to OasRails
+
+OasRails automatically generates interactive documentation for your Rails APIs using the OpenAPI Specification 3.1 (OAS 3.1) and displays it with a nice UI.
+
+## Getting Started
+
+You've successfully mounted the OasRails engine. This default documentation is based on your routes and automatically gathered information.
+
+## Enhancing Your Documentation
+
+To customize and enrich your API documentation:
+
+1. Generate an initializer file:
+
+  ```
+  rails generate oas_rails:config
+  ```
+2. Edit the created `config/initializers/oas_rails.rb` file to override default settings and add project-specific information.
+
+3. Use Yard tags in your controller methods to provide detailed API endpoint descriptions.
+
+## Features
+
+- Automatic OAS 3.1 document generation
+- [RapiDoc](https://github.com/rapi-doc/RapiDoc) integration for interactive exploration
+- Minimal setup required for basic documentation
+- Extensible through configuration and Yard tags
+
+Explore your API documentation and enjoy the power of OasRails!
+
+For more information and advanced usage, visit the [OasRails GitHub repository](https://github.com/a-chacon/oas_rails).
+
+      "
+    end
+  end
+end

data/lib/oas_rails/license.rb

@@ -0,0 +1,11 @@
+module OasRails
+  class License < OasBase
+    attr_accessor :name, :url
+
+    def initialize(**kwargs)
+      super()
+      @name = kwargs[:name] || 'GPL 3.0'
+      @url = kwargs[:url] || 'https://www.gnu.org/licenses/gpl-3.0.html#license-text'
+    end
+  end
+end

data/lib/oas_rails/media_type.rb

@@ -0,0 +1,57 @@
+module OasRails
+  class MediaType < OasBase
+    attr_accessor :schema, :example, :examples, :encoding
+
+    def initialize(schema:, **kwargs)
+      super()
+      @schema = schema
+      @example = kwargs[:example] || {}
+      @examples = kwargs[:examples] || []
+    end
+
+    class << self
+      def from_model_class(klass:, examples: {})
+        return unless klass.ancestors.include? ActiveRecord::Base
+
+        model_schema = Esquema::Builder.new(klass).build_schema.as_json
+        model_schema["required"] = []
+        schema = { type: "object", properties: { klass.to_s.downcase => model_schema } }
+        examples.merge!(search_for_examples_in_tests(klass:))
+        new(media_type: "", schema:, examples:)
+      end
+
+      def search_for_examples_in_tests(klass:)
+        case OasRails.detect_test_framework
+        when :factory_bot
+          {}
+          # TODO: create examples with FactoryBot
+        when :fixtures
+          # Handle fixtures scenario
+          fixture_file = Rails.root.join('test', 'fixtures', "#{klass.to_s.pluralize.downcase}.yml")
+          fixture_data = YAML.load_file(fixture_file).with_indifferent_access
+
+          users_hash = {}
+
+          # Convert the fixture data to a hash
+          fixture_data.each do |name, attributes|
+            users_hash[name] = { value: { klass.to_s.downcase => attributes } }
+          end
+          users_hash
+        else
+          {}
+        end
+      end
+
+      def tags_to_examples(tags:)
+        tags.each_with_object({}).with_index(1) do |(example, result), _index|
+          key = example.text.downcase.gsub(' ', '_')
+          value = {
+            "summary" => example.text,
+            "value" => example.content
+          }
+          result[key] = value
+        end
+      end
+    end
+  end
+end

data/lib/oas_rails/oas_base.rb

@@ -0,0 +1,29 @@
+module OasRails
+  class OasBase
+    def to_spec
+      hash = {}
+      instance_variables.each do |var|
+        key = var.to_s.delete('@')
+        camel_case_key = key.camelize(:lower).to_sym
+        value = instance_variable_get(var)
+
+        processed_value = if value.respond_to?(:to_spec)
+                            value.to_spec
+                          else
+                            value
+                          end
+
+        hash[camel_case_key] = processed_value unless (processed_value.is_a?(Hash) || processed_value.is_a?(Array)) && processed_value.empty?
+      end
+      hash
+    end
+
+    private
+
+    def snake_to_camel(snake_str)
+      words = snake_str.to_s.split('_')
+      words[1..].map!(&:capitalize)
+      (words[0] + words[1..].join).to_sym
+    end
+  end
+end