oas_rails 0.2.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c6823d6b64ffb6edbeabed87d2985f006433d6c8243d6e42bf21a6c96fab1e1
-  data.tar.gz: 85e8a04aa51388ce0ba2f0e27da7c81176ecc1e62630e301147ac0d1bd57fbac
+  metadata.gz: 785755b5aed419ca89dc279c2965e5de19cc32bfcbd444a6cb2d25da2704fc8c
+  data.tar.gz: 774eac0d5dfb757e23b40c2ce90a1eab929615241109824b86696e481b06ab99
 SHA512:
-  metadata.gz: cfd37bb135fcbe966a2ad9972f5339f9c3c196cc10234a65570e023d8ae4386f4d55bac813f51c3da6cb5f4d2f29c49c8294f29eb391d405fa437fe5c5b34375
-  data.tar.gz: 49e84dddf1baeb860ae753757a72c5a9989e4c1fd49dcc9b9beb79ea52323a330eb054236e3329756192e68fd43c2cc1ec9f0ea6f269082c0191d4ca184b5596
+  metadata.gz: 58ce0d42fa52b4bbc2c2d5c3bf81e3f23f0e859c62eb2145b63376873ca405f8ee6325b2c447a28b2cd4abd94e74af96986de96fc5ab2c5422b0a8e80a3e83a9
+  data.tar.gz: 537809a2b7dc85e3d66d1d0c06fd677527e06cc6fb5ba390189cc909dc8c912511677ad5686904e0636254b7d78a79cec85bff7ac4a1ae49a2e7c330a7a87aaf

data/README.md

@@ -6,7 +6,7 @@
 
 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)**.
 
-![Screenshot](https://raw.githubusercontent.com/a-chacon/oas_rails/0cfc9abb5be85e6bb3fc4669e29372be8f80a276/oas_rails_ui.png)
+![Screenshot](https://a-chacon.com/assets/images/oas_rails_ui.png)
 
 ## Related Projects
 
@@ -39,6 +39,7 @@ The goal is to minimize the effort required to create comprehensive documentatio
   - [Tag Information](#tag-information)
   - [Optional Settings](#optional-settings)
   - [Authentication Settings](#authentication-settings)
+  - [Default Responses (Errors)](#default-responses)
 - [Usage](#usage)
   - [Documenting Your Endpoints](#documenting-your-endpoints)
   - [Example](#example-of-documented-endpoints)
@@ -110,6 +111,14 @@ Then fill it with your data. Below are the available configuration options:
 - `config.security_schema`: The default security schema used for authentication. Choose a predefined security schema from `[:api_key_cookie, :api_key_header, :api_key_query, :basic, :bearer, :bearer_jwt, :mutual_tls]`.
 - `config.security_schemas`: Custom security schemas. Follow the [OpenAPI Specification](https://spec.openapis.org/oas/latest.html#security-scheme-object) for defining these schemas.
 
+### Default Errors
+
+- `config.set_default_responses`: Determines whether to add default errors responses to endpoint. Default is `true`.
+
+- `config.possible_default_responses`: Array with possible default errors.(Some will be added depending on the endpoint, example: not_found only works with show/update/delete). Default: [:not_found, :unauthorized, :forbidden]. It should be HTTP status code symbols from the list: `[:not_found, :unauthorized, :forbidden, :internal_server_error, :unprocessable_entity]`
+
+- `config.response_body_of_default`: body for use in default responses. It must be a Hash. Default: { message: String }
+
 ## Usage
 
 In addition to the information provided in the initializer file and the data that can be extracted from the routes and methods automatically, it is essential to document your API in the following way. The documentation is created **with the help of YARD**, so the methods are documented with **comment tags**.

data/app/controllers/oas_rails/oas_rails_controller.rb

@@ -6,7 +6,7 @@ module OasRails
       respond_to do |format|
         format.html
         format.json do
-          render json: Specification.new.to_json, status: :ok
+          render json: OasRails.build.to_json, status: :ok
         end
       end
     end

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

@@ -86,4 +86,15 @@ OasRails.configure do |config|
   #   "in": "header"
   #  }
   # }
+
+  # ###########################
+  # Default Responses (Errors)
+  # ###########################
+
+  # The default responses errors are setted only if the action allow it.
+  # Example, if you add forbidden then it will be added only if the endpoint requires authentication.
+  # Example: not_found will be setted to the endpoint only if the operation is a show/update/destroy action.
+  # config.set_default_responses = true
+  # config.possible_default_responses = [:not_found, :unauthorized, :forbidden]
+  # config.response_body_of_default = { message: String }
 end

data/lib/oas_rails/builders/content_builder.rb

@@ -0,0 +1,55 @@
+module OasRails
+  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 from_model_class(klass)
+        return self unless klass.ancestors.include? ActiveRecord::Base
+
+        model_schema = EsquemaBuilder.send("build_#{@context}_schema", klass:)
+        model_schema["required"] = []
+        schema = { type: "object", properties: { klass.to_s.downcase => model_schema } }
+        examples = Spec::MediaType.search_for_examples_in_tests(klass, context: @context)
+        @media_type.schema = @specification.components.add_schema(schema)
+        @media_type.examples = @media_type.examples.merge(examples)
+
+        self
+      end
+
+      def build
+        {
+          "application/json": @media_type
+        }
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/operation_builder.rb

@@ -0,0 +1,32 @@
+module OasRails
+  module Builders
+    class OperationBuilder
+      include Extractors::OasRouteExtractor
+
+      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_autodiscovered_responses(oas_route)
+                                               .add_default_responses(oas_route, !@operation.security.empty?).build
+
+        self
+      end
+
+      def build
+        @operation
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/parameter_builder.rb

@@ -0,0 +1,28 @@
+module OasRails
+  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] : nil
+      end
+
+      def build
+        @parameter
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/parameters_builder.rb

@@ -0,0 +1,39 @@
+module OasRails
+  module Builders
+    class ParametersBuilder
+      def initialize(specification)
+        @specification = specification
+        @parameters = []
+      end
+
+      def from_oas_route(oas_route)
+        parameters_from_tags(tags: oas_route.docstring.tags(:parameter))
+        oas_route.path_params.try(:map) do |p|
+          @parameters << ParameterBuilder.new(@specification).from_path(oas_route.path, p).build unless @parameters.any? { |param| param.name.to_s == p.to_s }
+        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_rails/builders/path_item_builder.rb

@@ -0,0 +1,22 @@
+module OasRails
+  module Builders
+    class PathItemBuilder
+      def initialize(specification)
+        @specification = specification
+        @path_item = Spec::PathItem.new(specification)
+      end
+
+      def from_path(path, route_extractor: Extractors::RouteExtractor)
+        route_extractor.host_routes_by_path(path).each do |oas_route|
+          @path_item.add_operation(oas_route.verb.downcase, OperationBuilder.new(@specification).from_oas_route(oas_route).build)
+        end
+
+        self
+      end
+
+      def build
+        @path_item
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/request_body_builder.rb

@@ -0,0 +1,60 @@
+module OasRails
+  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.docstring.tags(:request_body).first
+        if tag_request_body.nil? && OasRails.config.autodiscover_request_body
+          detect_request_body(oas_route) if %w[create update].include? oas_route.method
+        elsif !tag_request_body.nil?
+          from_tags(tag: tag_request_body, examples_tags: oas_route.docstring.tags(:request_body_example))
+        end
+
+        self
+      end
+
+      def from_tags(tag:, examples_tags: [])
+        if tag.klass.ancestors.include? ActiveRecord::Base
+          from_model_class(klass: tag.klass, description: tag.text, required: tag.required, examples_tags:)
+        else
+          @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
+        end
+
+        self
+      end
+
+      def from_model_class(klass:, **kwargs)
+        @request_body.description = kwargs[:description] || klass.to_s
+        @request_body.content = ContentBuilder.new(@specification, :incoming).from_model_class(klass).with_examples_from_tags(kwargs[:examples_tags] || {}).build
+        @request_body.required = kwargs[: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
+
+      private
+
+      def detect_request_body(oas_route)
+        klass = oas_route.controller.singularize.camelize.constantize
+        from_model_class(klass:, required: true)
+      end
+    end
+  end
+end

data/lib/oas_rails/builders/response_builder.rb

@@ -0,0 +1,40 @@
+module OasRails
+  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_rails/builders/responses_builder.rb

@@ -0,0 +1,58 @@
+module OasRails
+  module Builders
+    class ResponsesBuilder
+      def initialize(specification)
+        @specification = specification
+        @responses = Spec::Responses.new(specification)
+      end
+
+      def from_oas_route(oas_route)
+        oas_route.docstring.tags(:response).each do |tag|
+          @responses.add_response(ResponseBuilder.new(@specification).from_tag(tag).build)
+        end
+
+        self
+      end
+
+      def add_autodiscovered_responses(oas_route)
+        return unless OasRails.config.autodiscover_responses
+
+        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 unless OasRails.config.set_default_responses
+
+        content = ContentBuilder.new(@specification, :outgoing).with_schema(Utils.hash_to_json_schema(OasRails.config.response_body_of_default)).build
+        common_errors = []
+        common_errors.push(:unauthorized, :forbidden) if security
+
+        case oas_route.method
+        when "show", "update", "destroy"
+          common_errors.push(:not_found)
+        when "create", "index"
+          # possible errors for this methods?
+        end
+
+        (OasRails.config.possible_default_responses & common_errors).each do |e|
+          code = Utils.status_to_integer(e)
+          response = ResponseBuilder.new(@specification).with_code(code).with_description(Utils.get_definition(code)).with_content(content).build
+
+          @responses.add_response(response) if @responses.responses[response.code].blank?
+        end
+
+        self
+      end
+
+      def build
+        @responses
+      end
+    end
+  end
+end

data/lib/oas_rails/configuration.rb

@@ -1,10 +1,19 @@
 module OasRails
   class Configuration
-    attr_accessor :info, :default_tags_from, :autodiscover_request_body, :autodiscover_responses, :api_path, :security_schemas, :authenticate_all_routes_by_default
+    attr_accessor :info,
+                  :default_tags_from,
+                  :autodiscover_request_body,
+                  :autodiscover_responses,
+                  :api_path,
+                  :security_schemas,
+                  :authenticate_all_routes_by_default,
+                  :set_default_responses,
+                  :possible_default_responses,
+                  :response_body_of_default
     attr_reader :servers, :tags, :security_schema
 
     def initialize
-      @info = Info.new
+      @info = Spec::Info.new
       @servers = default_servers
       @tags = []
       @swagger_version = '3.1.0'
@@ -15,6 +24,9 @@ module OasRails
       @authenticate_all_routes_by_default = true
       @security_schema = nil
       @security_schemas = {}
+      @set_default_responses = true
+      @possible_default_responses = [:not_found, :unauthorized, :forbidden]
+      @response_body_of_default = { message: String }
     end
 
     def security_schema=(value)
@@ -24,15 +36,23 @@ module OasRails
     end
 
     def default_servers
-      [Server.new(url: "http://localhost:3000", description: "Rails Default Development Server")]
+      [Spec::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]) }
+      @servers = value.map { |s| Spec::Server.new(url: s[:url], description: s[:description]) }
     end
 
     def tags=(value)
-      @tags = value.map { |t| Tag.new(name: t[:name], description: t[:description]) }
+      @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
   end
 

data/lib/oas_rails/esquema_builder.rb

@@ -0,0 +1,37 @@
+module OasRails
+  module EsquemaBuilder
+    class << self
+      # Builds a schema for a class when it is used as incoming API data.
+      #
+      # @param klass [Class] The class for which the schema is built.
+      # @return [Hash] The schema as a JSON-compatible hash.
+      def build_incoming_schema(klass:)
+        configure_common_settings
+        Esquema.configuration.excluded_columns = OasRails.config.excluded_columns_incoming
+
+        Esquema::Builder.new(klass).build_schema.as_json
+      end
+
+      # Builds a schema for a class when it is used as outgoing API data.
+      #
+      # @param klass [Class] The class for which the schema is built.
+      # @return [Hash] The schema as a JSON-compatible hash.
+      def build_outgoing_schema(klass:)
+        configure_common_settings
+        Esquema.configuration.excluded_columns = OasRails.config.excluded_columns_outgoing
+
+        Esquema::Builder.new(klass).build_schema.as_json
+      end
+
+      private
+
+      # Configures common settings for schema building.
+      #
+      # Excludes associations and foreign keys from the schema.
+      def configure_common_settings
+        Esquema.configuration.exclude_associations = true
+        Esquema.configuration.exclude_foreign_keys = true
+      end
+    end
+  end
+end

data/lib/oas_rails/extractors/oas_route_extractor.rb

@@ -0,0 +1,66 @@
+module OasRails
+  module Extractors
+    module OasRouteExtractor
+      def extract_summary(oas_route:)
+        oas_route.docstring.tags(:summary).first.try(:text) || generate_crud_name(oas_route.method, oas_route.controller.downcase) || "#{oas_route.verb} #{oas_route.path}"
+      end
+
+      def extract_operation_id(oas_route:)
+        "#{oas_route.method}#{oas_route.path.gsub('/', '_').gsub(/[{}]/, '')}"
+      end
+
+      def extract_tags(oas_route:)
+        tags = oas_route.docstring.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 OasRails.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.titleize
+        end
+        tags
+      end
+
+      def extract_security(oas_route:)
+        return [] if oas_route.docstring.tags(:no_auth).any?
+
+        if (methods = oas_route.docstring.tags(:auth).first)
+          OasRails.config.security_schemas.keys.map { |key| { key => [] } }.select do |schema|
+            methods.types.include?(schema.keys.first.to_s)
+          end
+        elsif OasRails.config.authenticate_all_routes_by_default
+          OasRails.config.security_schemas.keys.map { |key| { key => [] } }
+        else
+          []
+        end
+      end
+
+      private
+
+      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