oas_core 0.0.1

data/README.md

@@ -0,0 +1,70 @@
+![Gem Version](https://img.shields.io/gem/v/oas_core?color=E9573F)
+![GitHub License](https://img.shields.io/github/license/a-chacon/oas_core?color=blue)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/a-chacon/oas_core/.github%2Fworkflows%2Frubyonrails.yml)
+![Gem Total Downloads](https://img.shields.io/gem/dt/oas_core)
+![Static Badge](https://img.shields.io/badge/Rails-%3E%3D7.0.0-%23E9573F)
+![Static Badge](https://img.shields.io/badge/Ruby-%3E%3D3.1.0-%23E9573F)
+
+# 📃Open API Specification For Rails
+
+OasCore 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)**.
+
+### 🚀 Demo App
+
+Explore the interactive documentation live:
+
+🔗 **[Open Demo App](https://paso.fly.dev/api/docs)**  
+👤 **Username**: `oasrails`  
+🔑 **Password**: `oasrails`
+
+🎬 A Demo Installation/Usage Video:
+<https://vimeo.com/1013687332>
+🎬
+
+![Screenshot](https://a-chacon.com/assets/images/oas_core_ui.png)
+
+## 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 OasCore 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.
+
+## Documentation
+
+For see how to install, configure and use OasCore please refere to the [OasCoreBook](http://a-chacon.com/oas_core)
+
+## 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!
+
+If you plan a big feature, first open an issue to discuss it before any development.
+
+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
+
+## 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).
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=a-chacon/oas_core&type=Date)](https://www.star-history.com/#a-chacon/oas_core&Date)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/oas_core/builders/content_builder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Builders
+    class ContentBuilder
+      def initialize(specification, context)
+        @context = context || :incoming
+        @specification = specification
+        @media_type = Spec::MediaType.new(specification)
+      end
+
+      def with_schema(schema)
+        @media_type.schema = @specification.components.add_schema(schema)
+
+        self
+      end
+
+      def with_examples(examples)
+        @media_type.examples = @specification.components.add_example(examples)
+
+        self
+      end
+
+      def with_examples_from_tags(tags)
+        @media_type.examples = @media_type.examples.merge(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] = @specification.components.add_example(value)
+        end)
+
+        self
+      end
+
+      def build
+        {
+          'application/json': @media_type
+        }
+      end
+    end
+  end
+end

data/lib/oas_core/builders/operation_builder.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Builders
+    class OperationBuilder
+      def initialize(specification)
+        @specification = specification
+        @operation = Spec::Operation.new(specification)
+      end
+
+      def from_oas_route(oas_route)
+        @operation.summary = extract_summary(oas_route:)
+        @operation.operation_id = extract_operation_id(oas_route:)
+        @operation.description = oas_route.docstring
+        @operation.tags = extract_tags(oas_route:)
+        @operation.security = extract_security(oas_route:)
+        @operation.parameters = ParametersBuilder.new(@specification).from_oas_route(oas_route).build
+        @operation.request_body = RequestBodyBuilder.new(@specification).from_oas_route(oas_route).reference
+        @operation.responses = ResponsesBuilder.new(@specification)
+                                               .from_oas_route(oas_route)
+                                               .add_default_responses(oas_route, !@operation.security.empty?).build
+
+        self
+      end
+
+      def build
+        @operation
+      end
+
+      private
+
+      def extract_summary(oas_route:)
+        oas_route.tags(:summary).first.try(:text) || generate_crud_name(oas_route.method_name,
+                                                                        oas_route.controller.downcase) || "#{oas_route.verb} #{oas_route.path}"
+      end
+
+      def extract_operation_id(oas_route:)
+        "#{oas_route.method_name}#{oas_route.path.gsub('/', '_').gsub(/[{}]/, '')}"
+      end
+
+      def extract_tags(oas_route:)
+        tags = oas_route.tags(:tags).first
+        if tags.nil?
+          default_tags(oas_route:)
+        else
+          tags.text.split(',').map(&:strip).map(&:titleize)
+        end
+      end
+
+      def default_tags(oas_route:)
+        tags = []
+        if OasCore.config.default_tags_from == :namespace
+          tag = oas_route.path.split('/').reject(&:empty?).first.try(:titleize)
+          tags << tag unless tag.nil?
+        else
+          tags << oas_route.controller.gsub('/', ' ').titleize
+        end
+
+        tags
+      end
+
+      def extract_security(oas_route:)
+        return [] if oas_route.tags(:no_auth).any?
+
+        if (methods = oas_route.tags(:auth).first)
+          OasCore.config.security_schemas.keys.map { |key| { key => [] } }.select do |schema|
+            methods.types.include?(schema.keys.first.to_s)
+          end
+        elsif OasCore.config.authenticate_all_routes_by_default
+          OasCore.config.security_schemas.keys.map { |key| { key => [] } }
+        else
+          []
+        end
+      end
+
+      def generate_crud_name(method, controller)
+        controller_name = controller.to_s.underscore.humanize.downcase.pluralize
+
+        case method.to_sym
+        when :index
+          "List #{controller_name}"
+        when :show
+          "View #{controller_name.singularize}"
+        when :create
+          "Create new #{controller_name.singularize}"
+        when :update
+          "Update #{controller_name.singularize}"
+        when :destroy
+          "Delete #{controller_name.singularize}"
+        end
+      end
+    end
+  end
+end

data/lib/oas_core/builders/parameter_builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Builders
+    class ParameterBuilder
+      def initialize(specification)
+        @specification = specification
+        @parameter = Spec::Parameter.new(specification)
+      end
+
+      def from_path(path, param)
+        @parameter.name = param
+        @parameter.in = 'path'
+        @parameter.description = "#{param.split('_')[-1].titleize} of existing #{extract_word_before(path,
+                                                                                                     param).singularize}."
+
+        self
+      end
+
+      def extract_word_before(string, param)
+        regex = %r{/([\w-]+)/\{#{param}\}}
+        match = string.match(regex)
+        match ? match[1] : ''
+      end
+
+      def build
+        @parameter
+      end
+    end
+  end
+end

data/lib/oas_core/builders/parameters_builder.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Builders
+    class ParametersBuilder
+      def initialize(specification)
+        @specification = specification
+        @parameters = []
+      end
+
+      def from_oas_route(oas_route)
+        parameters_from_tags(tags: oas_route.tags(:parameter))
+        oas_route.path_params.try(:map) do |p|
+          unless @parameters.any? do |param|
+            param.name.to_s == p.to_s
+          end
+            @parameters << ParameterBuilder.new(@specification).from_path(oas_route.path,
+                                                                          p).build
+          end
+        end
+
+        self
+      end
+
+      def parameters_from_tags(tags:)
+        tags.each do |t|
+          parameter = Spec::Parameter.new(@specification)
+          parameter.name = t.name
+          parameter.in = t.location
+          parameter.required = t.required
+          parameter.schema = t.schema
+          parameter.description = t.text
+          @parameters << parameter
+        end
+
+        self
+      end
+
+      def build
+        @parameters.map do |p|
+          @specification.components.add_parameter(p)
+        end
+      end
+    end
+  end
+end

data/lib/oas_core/builders/path_item_builder.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Builders
+    class PathItemBuilder
+      def initialize(specification)
+        @specification = specification
+        @path_item = Spec::PathItem.new(specification)
+      end
+
+      def with_oas_routes(oas_routes)
+        oas_routes.each do |oas_route|
+          oas_route.verb.downcase.split('|').each do |v|
+            @path_item.add_operation(v, OperationBuilder.new(@specification).from_oas_route(oas_route).build)
+          end
+        end
+
+        self
+      end
+
+      def build
+        @path_item
+      end
+    end
+  end
+end

data/lib/oas_core/builders/request_body_builder.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Builders
+    class RequestBodyBuilder
+      def initialize(specification)
+        @specification = specification
+        @request_body = Spec::RequestBody.new(specification)
+      end
+
+      def from_oas_route(oas_route)
+        tag_request_body = oas_route.tags(:request_body).first
+        # TODO: This is for frameowkr specific.
+        # if tag_request_body.nil? && OasCore.config.autodiscover_request_body
+        #   detect_request_body(oas_route) if %w[create update].include? oas_route.method_name
+        return self if tag_request_body.nil?
+
+        from_tags(tag: tag_request_body, examples_tags: oas_route.tags(:request_body_example))
+
+        self
+      end
+
+      def from_tags(tag:, examples_tags: [])
+        @request_body.description = tag.text
+        @request_body.content = ContentBuilder.new(@specification,
+                                                   :incoming).with_schema(tag.schema).with_examples_from_tags(examples_tags).build
+        @request_body.required = tag.required
+
+        self
+      end
+
+      def build
+        return {} if @request_body.content == {}
+
+        @request_body
+      end
+
+      def reference
+        return {} if @request_body.content == {}
+
+        @specification.components.add_request_body(@request_body)
+      end
+    end
+  end
+end

data/lib/oas_core/builders/response_builder.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Builders
+    class ResponseBuilder
+      def initialize(specification)
+        @specification = specification
+        @response = Spec::Response.new(specification)
+      end
+
+      def with_description(description)
+        @response.description = description
+
+        self
+      end
+
+      def with_content(content)
+        @response.content = content
+
+        self
+      end
+
+      def with_code(code)
+        @response.code = code
+
+        self
+      end
+
+      def from_tag(tag)
+        @response.code = tag.name.to_i
+        @response.description = tag.text
+        @response.content = ContentBuilder.new(@specification, :outgoing).with_schema(tag.schema).build
+
+        self
+      end
+
+      def build
+        @response
+      end
+    end
+  end
+end

data/lib/oas_core/builders/responses_builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Builders
+    class ResponsesBuilder
+      def initialize(specification, content_builder: ContentBuilder, response_builder: ResponseBuilder,
+                     json_schema_generator: JsonSchemaGenerator, utils: Utils)
+        @specification = specification
+        @content_builder = content_builder
+        @response_builder = response_builder
+        @json_schema_generator = json_schema_generator
+        @utils = utils
+        @responses = Spec::Responses.new(specification)
+      end
+
+      def from_oas_route(oas_route)
+        oas_route.tags(:response).each do |tag|
+          content = @content_builder.new(@specification,
+                                         :outgoing).with_schema(tag.schema).with_examples_from_tags(oas_route.tags(:response_example).filter do |re|
+                                                                                                      re.code == tag.name
+                                                                                                    end).build
+          response = @response_builder.new(@specification).with_code(tag.name.to_i).with_description(tag.text).with_content(content).build
+
+          @responses.add_response(response)
+        end
+
+        self
+      end
+
+      # def add_autodiscovered_responses(oas_route)
+      #   return self if !OasCore.config.autodiscover_responses || oas_route.tags(:response).any?
+      #
+      #   new_responses = Extractors::RenderResponseExtractor.extract_responses_from_source(@specification, source: oas_route.source_string)
+      #
+      #   new_responses.each do |new_response|
+      #     @responses.add_response(new_response) if @responses.responses[new_response.code].blank?
+      #   end
+      #
+      #   self
+      # end
+
+      def add_default_responses(oas_route, security)
+        return self unless OasCore.config.set_default_responses
+
+        common_errors = determine_common_errors(oas_route, security)
+        add_responses_for_errors(common_errors)
+
+        self
+      end
+
+      def build
+        @responses
+      end
+
+      private
+
+      def determine_common_errors(oas_route, security)
+        common_errors = []
+        common_errors.push(:unauthorized, :forbidden, :internal_server_error) if security
+
+        case oas_route.method_name
+        when 'show', 'destroy'
+          common_errors.push(:not_found)
+        when 'create'
+          common_errors.push(:unprocessable_entity)
+        when 'update'
+          common_errors.push(:not_found, :unprocessable_entity)
+        end
+
+        OasCore.config.possible_default_responses & common_errors
+      end
+
+      def add_responses_for_errors(errors)
+        errors.each do |error|
+          response_body = resolve_response_body(error)
+          content = @content_builder.new(@specification,
+                                         :outgoing).with_schema(@json_schema_generator.process_string(response_body)[:json_schema]).build
+          code = @utils.status_to_integer(error)
+          response = @response_builder.new(@specification).with_code(code).with_description(@utils.get_definition(code)).with_content(content).build
+
+          @responses.add_response(response) if @responses.responses[response.code].nil?
+        end
+      end
+
+      def resolve_response_body(error)
+        OasCore.config.public_send("response_body_of_#{error}")
+      rescue StandardError
+        OasCore.config.response_body_of_default
+      end
+    end
+  end
+end

data/lib/oas_core/builders/specification_builder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module OasCore
+  module Builders
+    class SpecificationBuilder
+      def initialize
+        @specification = Spec::Specification.new
+      end
+
+      def with_oas_routes(oas_routes)
+        grouped_routes = oas_routes.group_by(&:path)
+        grouped_routes.each do |path, routes|
+          @specification.paths.add_path(path, routes)
+        end
+
+        self
+      end
+
+      def build
+        @specification
+      end
+    end
+  end
+end

data/lib/oas_core/configuration.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module OasCore
+  class Configuration
+    attr_accessor :info,
+                  :layout,
+                  :default_tags_from,
+                  :autodiscover_request_body,
+                  :autodiscover_responses,
+                  :api_path,
+                  :ignored_actions,
+                  :security_schemas,
+                  :authenticate_all_routes_by_default,
+                  :set_default_responses,
+                  :possible_default_responses,
+                  :http_verbs,
+                  :use_model_names,
+                  :rapidoc_theme
+
+    attr_reader :servers, :tags, :security_schema, :include_mode, :response_body_of_default
+
+    def initialize
+      @info = Spec::Info.new
+      @layout = false
+      @servers = default_servers
+      @tags = []
+      @swagger_version = '3.1.0'
+      @default_tags_from = :namespace
+      @autodiscover_request_body = true
+      @autodiscover_responses = true
+      @api_path = '/'
+      @ignored_actions = []
+      @authenticate_all_routes_by_default = true
+      @security_schema = nil
+      @security_schemas = {}
+      @set_default_responses = true
+      @possible_default_responses = %i[not_found unauthorized forbidden internal_server_error
+                                       unprocessable_entity]
+      @http_verbs = %i[get post put patch delete]
+      @response_body_of_default = 'Hash{ status: !Integer, error: String }'
+      @use_model_names = false
+      @rapidoc_theme = :rails
+      @include_mode = :all
+
+      @possible_default_responses.each do |response|
+        method_name = "response_body_of_#{response}="
+        variable_name = "@response_body_of_#{response}"
+
+        define_singleton_method(method_name) do |value|
+          raise ArgumentError, "#{method_name} must be a String With a valid object" unless value.is_a?(String)
+
+          OasCore::JsonSchemaGenerator.parse_type(value)
+          instance_variable_set(variable_name, value)
+        end
+
+        define_singleton_method("response_body_of_#{response}") do
+          instance_variable_get(variable_name) || @response_body_of_default
+        end
+      end
+    end
+
+    def security_schema=(value)
+      return unless (security_schema = DEFAULT_SECURITY_SCHEMES[value])
+
+      @security_schemas = { value => security_schema }
+    end
+
+    def default_servers
+      [Spec::Server.new(url: 'http://localhost:3000', description: 'Rails Default Development Server')]
+    end
+
+    def servers=(value)
+      @servers = value.map { |s| Spec::Server.new(url: s[:url], description: s[:description]) }
+    end
+
+    def tags=(value)
+      @tags = value.map { |t| Spec::Tag.new(name: t[:name], description: t[:description]) }
+    end
+
+    def excluded_columns_incoming
+      %i[id created_at updated_at deleted_at]
+    end
+
+    def excluded_columns_outgoing
+      []
+    end
+
+    def include_mode=(value)
+      valid_modes = %i[all with_tags explicit]
+      raise ArgumentError, "include_mode must be one of #{valid_modes}" unless valid_modes.include?(value)
+
+      @include_mode = value
+    end
+
+    def response_body_of_default=(value)
+      raise ArgumentError, 'response_body_of_default must be a String With a valid object' unless value.is_a?(String)
+
+      OasCore::JsonSchemaGenerator.parse_type(value)
+      @response_body_of_default = value
+    end
+  end
+
+  DEFAULT_SECURITY_SCHEMES = {
+    api_key_cookie: {
+      type: 'apiKey',
+      in: 'cookie',
+      name: 'api_key',
+      description: 'An API key that will be supplied in a named cookie.'
+    },
+    api_key_header: {
+      type: 'apiKey',
+      in: 'header',
+      name: 'X-API-Key',
+      description: 'An API key that will be supplied in a named header.'
+    },
+    api_key_query: {
+      type: 'apiKey',
+      in: 'query',
+      name: 'apiKey',
+      description: 'An API key that will be supplied in a named query parameter.'
+    },
+    basic: {
+      type: 'http',
+      scheme: 'basic',
+      description: "Basic auth that takes a base64'd combination of `user:password`."
+    },
+    bearer: {
+      type: 'http',
+      scheme: 'bearer',
+      description: 'A bearer token that will be supplied within an `Authorization` header as `bearer <token>`.'
+    },
+    bearer_jwt: {
+      type: 'http',
+      scheme: 'bearer',
+      bearerFormat: 'JWT',
+      description: 'A bearer token that will be supplied within an `Authorization` header as `bearer <token>`. In this case, the format of the token is specified as JWT.'
+    },
+    mutual_tls: {
+      type: 'mutualTLS',
+      description: 'Requires a specific mutual TLS certificate to use when making an HTTP request.'
+    }
+  }.freeze
+end