betterdocs 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84f61a235deb0348813dd4ccfc102e41e08ce374b3bcc7d48991935d08f1ce17
-  data.tar.gz: dee9b3cfb105cea04192377d5f1b11306aee02da2165bc85c78eeaa2d239089c
+  metadata.gz: 7324105b58e4926bdbcec0e372efda88e523c1c31fb4f0181e9d4cebc94b135c
+  data.tar.gz: 6926a2ea9814cae5e763113badf138104f2fd9ae250c57e9cc8a16fb6eb18d43
 SHA512:
-  metadata.gz: ca0afd3ada7b6852b0dda51e73457f37144b0c851fba52da52177ab81f76d22afe9f322b17f9e5a1d5fb965c7c0c4d0439a708fc112dd18de474880a2b97c711
-  data.tar.gz: c095d79714edc2c0cc66eae7bd7c76b4f6791d989f20826a0081e6c7661d928744dfd260d4be03884a6955bcfbffcbe1639fc52b02993b952e0f06c75b9b5117
+  metadata.gz: ccaab04fbb9dfc351d79b9b722d1430c1a8afc5007f3f8bfd68d2d7d1c06ab4d26cf843e745750d1eb805b3d83122fb6b48597a8c1a3bc127fee5bc95e43443e
+  data.tar.gz: 67968de292f5c9e0d17b0d2669d72ca75f1e6d709ea219de4f36beab3b99e14452dfa626ff4cb0fe6222419ba99e19f3be4f4765242dbd8d9f0622839d150cf9

data/.gitignore

@@ -3,6 +3,7 @@
 .DS_Store
 .bundle
 .byebug_history
+.history
 .ruby-version
 .rvmrc
 .utilsrc

data/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "cSpell.words": [
+        "Betterdocs",
+        "infobar"
+    ]
+}

data/Rakefile

@@ -12,7 +12,7 @@ GemHadar do
   test_dir    'spec'
   ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage', '.rvmrc',
     '.ruby-version', '.AppleDouble', 'tags', '.DS_Store', '.utilsrc',
-    '.bundle', '.byebug_history', 'errors.lst', '.yardoc'
+    '.bundle', '.byebug_history', 'errors.lst', '.yardoc', '.history'
   readme      'README.md'
   title       "#{name.camelize}"
 

data/VERSION

@@ -1 +1 @@
-0.7.1
+0.8.0

data/betterdocs.gemspec

@@ -1,18 +1,18 @@
 # -*- encoding: utf-8 -*-
-# stub: betterdocs 0.7.1 ruby lib
+# stub: betterdocs 0.8.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "betterdocs".freeze
-  s.version = "0.7.1"
+  s.version = "0.8.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["betterplace Developers".freeze]
-  s.date = "2021-06-01"
+  s.date = "2021-07-07"
   s.description = "This library provides tools to generate API documention for a web site's REST-ful JSON API.".freeze
   s.email = "developers@betterplace.org".freeze
-  s.extra_rdoc_files = ["README.md".freeze, "lib/betterdocs.rb".freeze, "lib/betterdocs/controller_collector.rb".freeze, "lib/betterdocs/dsl.rb".freeze, "lib/betterdocs/dsl/common.rb".freeze, "lib/betterdocs/dsl/controller.rb".freeze, "lib/betterdocs/dsl/controller/action.rb".freeze, "lib/betterdocs/dsl/controller/action/param.rb".freeze, "lib/betterdocs/dsl/controller/action/response.rb".freeze, "lib/betterdocs/dsl/controller/controller.rb".freeze, "lib/betterdocs/dsl/controller/controller_base.rb".freeze, "lib/betterdocs/dsl/json_params.rb".freeze, "lib/betterdocs/dsl/json_params/param.rb".freeze, "lib/betterdocs/dsl/json_type_mapper.rb".freeze, "lib/betterdocs/dsl/naming.rb".freeze, "lib/betterdocs/dsl/representer.rb".freeze, "lib/betterdocs/dsl/result.rb".freeze, "lib/betterdocs/dsl/result/collection_property.rb".freeze, "lib/betterdocs/dsl/result/link.rb".freeze, "lib/betterdocs/dsl/result/property.rb".freeze, "lib/betterdocs/generator/config_shortcuts.rb".freeze, "lib/betterdocs/generator/markdown.rb".freeze, "lib/betterdocs/global.rb".freeze, "lib/betterdocs/json_params_representer.rb".freeze, "lib/betterdocs/json_params_representer_collector.rb".freeze, "lib/betterdocs/json_time_with_zone.rb".freeze, "lib/betterdocs/mix_into_controller.rb".freeze, "lib/betterdocs/railtie.rb".freeze, "lib/betterdocs/rake_tasks.rb".freeze, "lib/betterdocs/representer.rb".freeze, "lib/betterdocs/result_representer.rb".freeze, "lib/betterdocs/result_representer_collector.rb".freeze, "lib/betterdocs/sanitizer.rb".freeze, "lib/betterdocs/section.rb".freeze, "lib/betterdocs/version.rb".freeze]
-  s.files = [".codeclimate.yml".freeze, ".gitignore".freeze, ".rspec".freeze, ".semaphore/semaphore.yml".freeze, ".tool-versions".freeze, "COPYING".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "betterdocs.gemspec".freeze, "lib/betterdocs.rb".freeze, "lib/betterdocs/controller_collector.rb".freeze, "lib/betterdocs/dsl.rb".freeze, "lib/betterdocs/dsl/common.rb".freeze, "lib/betterdocs/dsl/controller.rb".freeze, "lib/betterdocs/dsl/controller/action.rb".freeze, "lib/betterdocs/dsl/controller/action/param.rb".freeze, "lib/betterdocs/dsl/controller/action/response.rb".freeze, "lib/betterdocs/dsl/controller/controller.rb".freeze, "lib/betterdocs/dsl/controller/controller_base.rb".freeze, "lib/betterdocs/dsl/json_params.rb".freeze, "lib/betterdocs/dsl/json_params/param.rb".freeze, "lib/betterdocs/dsl/json_type_mapper.rb".freeze, "lib/betterdocs/dsl/naming.rb".freeze, "lib/betterdocs/dsl/representer.rb".freeze, "lib/betterdocs/dsl/result.rb".freeze, "lib/betterdocs/dsl/result/collection_property.rb".freeze, "lib/betterdocs/dsl/result/link.rb".freeze, "lib/betterdocs/dsl/result/property.rb".freeze, "lib/betterdocs/generator/config_shortcuts.rb".freeze, "lib/betterdocs/generator/markdown.rb".freeze, "lib/betterdocs/generator/markdown/templates/README.md.erb".freeze, "lib/betterdocs/generator/markdown/templates/section.md.erb".freeze, "lib/betterdocs/global.rb".freeze, "lib/betterdocs/json_params_representer.rb".freeze, "lib/betterdocs/json_params_representer_collector.rb".freeze, "lib/betterdocs/json_time_with_zone.rb".freeze, "lib/betterdocs/mix_into_controller.rb".freeze, "lib/betterdocs/railtie.rb".freeze, "lib/betterdocs/rake_tasks.rb".freeze, "lib/betterdocs/representer.rb".freeze, "lib/betterdocs/result_representer.rb".freeze, "lib/betterdocs/result_representer_collector.rb".freeze, "lib/betterdocs/sanitizer.rb".freeze, "lib/betterdocs/section.rb".freeze, "lib/betterdocs/tasks/doc.rake".freeze, "lib/betterdocs/version.rb".freeze, "spec/assets/app/assets/images/logos/logo.png".freeze, "spec/assets/app/controllers/api/foos_controller.rb".freeze, "spec/assets/app/views/api_v4/documentation/assets/CHANGELOG.md".freeze, "spec/assets/config/betterdocs.yml".freeze, "spec/betterdocs/dsl/controller/action/param_spec.rb".freeze, "spec/betterdocs/dsl/controller/action/response_spec.rb".freeze, "spec/betterdocs/dsl/json_type_mapper_spec.rb".freeze, "spec/betterdocs/dsl/result/collection_property_spec.rb".freeze, "spec/betterdocs/dsl/result/link_spec.rb".freeze, "spec/betterdocs/dsl/result/property_spec.rb".freeze, "spec/betterdocs/generator/markdown_spec.rb".freeze, "spec/betterdocs/global_spec.rb".freeze, "spec/betterdocs/json_params_representer_spec.rb".freeze, "spec/betterdocs/result_representer_spec.rb".freeze, "spec/betterdocs/sanitizer_spec.rb".freeze, "spec/controller_dsl_spec.rb".freeze, "spec/result_representer_dsl_spec.rb".freeze, "spec/spec_helper.rb".freeze]
+  s.extra_rdoc_files = ["README.md".freeze, "lib/betterdocs.rb".freeze, "lib/betterdocs/controller_collector.rb".freeze, "lib/betterdocs/dsl.rb".freeze, "lib/betterdocs/dsl/common.rb".freeze, "lib/betterdocs/dsl/controller.rb".freeze, "lib/betterdocs/dsl/controller/action.rb".freeze, "lib/betterdocs/dsl/controller/action/param.rb".freeze, "lib/betterdocs/dsl/controller/action/response.rb".freeze, "lib/betterdocs/dsl/controller/controller.rb".freeze, "lib/betterdocs/dsl/controller/controller_base.rb".freeze, "lib/betterdocs/dsl/json_params.rb".freeze, "lib/betterdocs/dsl/json_params/param.rb".freeze, "lib/betterdocs/dsl/json_type_mapper.rb".freeze, "lib/betterdocs/dsl/naming.rb".freeze, "lib/betterdocs/dsl/representer.rb".freeze, "lib/betterdocs/dsl/result.rb".freeze, "lib/betterdocs/dsl/result/collection_property.rb".freeze, "lib/betterdocs/dsl/result/link.rb".freeze, "lib/betterdocs/dsl/result/property.rb".freeze, "lib/betterdocs/generator/config_shortcuts.rb".freeze, "lib/betterdocs/generator/markdown.rb".freeze, "lib/betterdocs/generator/swagger.rb".freeze, "lib/betterdocs/global.rb".freeze, "lib/betterdocs/json_params_representer.rb".freeze, "lib/betterdocs/json_params_representer_collector.rb".freeze, "lib/betterdocs/json_time_with_zone.rb".freeze, "lib/betterdocs/mix_into_controller.rb".freeze, "lib/betterdocs/railtie.rb".freeze, "lib/betterdocs/rake_tasks.rb".freeze, "lib/betterdocs/representer.rb".freeze, "lib/betterdocs/result_representer.rb".freeze, "lib/betterdocs/result_representer_collector.rb".freeze, "lib/betterdocs/sanitizer.rb".freeze, "lib/betterdocs/section.rb".freeze, "lib/betterdocs/version.rb".freeze]
+  s.files = [".codeclimate.yml".freeze, ".gitignore".freeze, ".rspec".freeze, ".semaphore/semaphore.yml".freeze, ".tool-versions".freeze, ".vscode/settings.json".freeze, "COPYING".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "betterdocs.gemspec".freeze, "lib/betterdocs.rb".freeze, "lib/betterdocs/controller_collector.rb".freeze, "lib/betterdocs/dsl.rb".freeze, "lib/betterdocs/dsl/common.rb".freeze, "lib/betterdocs/dsl/controller.rb".freeze, "lib/betterdocs/dsl/controller/action.rb".freeze, "lib/betterdocs/dsl/controller/action/param.rb".freeze, "lib/betterdocs/dsl/controller/action/response.rb".freeze, "lib/betterdocs/dsl/controller/controller.rb".freeze, "lib/betterdocs/dsl/controller/controller_base.rb".freeze, "lib/betterdocs/dsl/json_params.rb".freeze, "lib/betterdocs/dsl/json_params/param.rb".freeze, "lib/betterdocs/dsl/json_type_mapper.rb".freeze, "lib/betterdocs/dsl/naming.rb".freeze, "lib/betterdocs/dsl/representer.rb".freeze, "lib/betterdocs/dsl/result.rb".freeze, "lib/betterdocs/dsl/result/collection_property.rb".freeze, "lib/betterdocs/dsl/result/link.rb".freeze, "lib/betterdocs/dsl/result/property.rb".freeze, "lib/betterdocs/generator/config_shortcuts.rb".freeze, "lib/betterdocs/generator/markdown.rb".freeze, "lib/betterdocs/generator/markdown/templates/README.md.erb".freeze, "lib/betterdocs/generator/markdown/templates/section.md.erb".freeze, "lib/betterdocs/generator/swagger.rb".freeze, "lib/betterdocs/generator/swagger_static/index.html".freeze, "lib/betterdocs/global.rb".freeze, "lib/betterdocs/json_params_representer.rb".freeze, "lib/betterdocs/json_params_representer_collector.rb".freeze, "lib/betterdocs/json_time_with_zone.rb".freeze, "lib/betterdocs/mix_into_controller.rb".freeze, "lib/betterdocs/railtie.rb".freeze, "lib/betterdocs/rake_tasks.rb".freeze, "lib/betterdocs/representer.rb".freeze, "lib/betterdocs/result_representer.rb".freeze, "lib/betterdocs/result_representer_collector.rb".freeze, "lib/betterdocs/sanitizer.rb".freeze, "lib/betterdocs/section.rb".freeze, "lib/betterdocs/tasks/doc.rake".freeze, "lib/betterdocs/version.rb".freeze, "spec/assets/app/assets/images/logos/logo.png".freeze, "spec/assets/app/controllers/api/foos_controller.rb".freeze, "spec/assets/app/views/api_v4/documentation/assets/CHANGELOG.md".freeze, "spec/assets/config/betterdocs.yml".freeze, "spec/betterdocs/dsl/controller/action/param_spec.rb".freeze, "spec/betterdocs/dsl/controller/action/response_spec.rb".freeze, "spec/betterdocs/dsl/json_type_mapper_spec.rb".freeze, "spec/betterdocs/dsl/result/collection_property_spec.rb".freeze, "spec/betterdocs/dsl/result/link_spec.rb".freeze, "spec/betterdocs/dsl/result/property_spec.rb".freeze, "spec/betterdocs/generator/markdown_spec.rb".freeze, "spec/betterdocs/global_spec.rb".freeze, "spec/betterdocs/json_params_representer_spec.rb".freeze, "spec/betterdocs/result_representer_spec.rb".freeze, "spec/betterdocs/sanitizer_spec.rb".freeze, "spec/controller_dsl_spec.rb".freeze, "spec/result_representer_dsl_spec.rb".freeze, "spec/spec_helper.rb".freeze]
   s.homepage = "http://github.com/betterplace/betterdocs".freeze
   s.rdoc_options = ["--title".freeze, "Betterdocs".freeze, "--main".freeze, "README.md".freeze]
   s.rubygems_version = "3.2.15".freeze

data/lib/betterdocs.rb

@@ -26,6 +26,7 @@ require 'betterdocs/section'
 require 'betterdocs/mix_into_controller'
 require 'betterdocs/generator/config_shortcuts'
 require 'betterdocs/generator/markdown'
+require 'betterdocs/generator/swagger'
 require 'betterdocs/rake_tasks'
 require 'betterdocs/json_time_with_zone'
 defined? Rails and require 'betterdocs/railtie'

data/lib/betterdocs/dsl/json_params/param.rb

@@ -1,3 +1,5 @@
+require 'active_support/time_with_zone'
+
 require 'betterdocs/dsl/naming'
 
 class Betterdocs::Dsl::JsonParams::Param < Betterdocs::Dsl::Representer

data/lib/betterdocs/dsl/result/property.rb

@@ -1,3 +1,5 @@
+require 'active_support/time_with_zone'
+
 require 'betterdocs/dsl/representer'
 require 'betterdocs/dsl/common'
 require 'betterdocs/dsl/naming'

data/lib/betterdocs/generator/swagger.rb

@@ -0,0 +1,405 @@
+require 'infobar'
+require 'fileutils'
+require 'term/ansicolor'
+require 'json'
+
+module Betterdocs
+  module Generator
+    class Swagger
+      include ::Betterdocs::Generator::ConfigShortcuts
+      include Term::ANSIColor
+      include FileUtils
+
+      def initialize(only: nil)
+        only and @only = Regexp.new(only)
+      end
+
+      def generate
+        if dir = config.swagger_output_directory.full?
+          generate_to dir
+        else
+          raise 'Specify an output_directory in your configuration!'
+        end
+      end
+
+      def generate_to(dirname)
+        map = { openapi: '3.0.2', paths: {}, components: { schemas: {} } }
+        add_error_envelope_schema(map[:components][:schemas])
+        configure_for_creation
+        prepare_dir(dirname)
+        add_global_info(map)
+        create_sections(map)
+        create_swagger(map, dirname)
+        create_assets
+        self
+      end
+
+      def configure_for_creation
+        infobar.puts color(40, "Setting asset_host to #{Betterdocs::Global.asset_host.inspect}.")
+        Betterdocs.rails.configuration.action_controller.asset_host = Betterdocs::Global.asset_host
+        options = {
+          host: Betterdocs::Global.api_host,
+          protocol: Betterdocs::Global.api_protocol,
+        }
+        infobar.puts color(40, "Setting default_url_options to #{options.inspect}.")
+        Betterdocs.rails.application.routes.default_url_options = options
+        self
+      end
+
+      def add_global_info(map)
+        slugs = get_request_url_slugs(sections.values.first.first.request)
+        map[:info] = { title: project_name, version: slugs[:ver] }
+        map[:servers] =
+          [{ url: "#{slugs[:protocol]}://#{[slugs[:host], slugs[:lang], "api_#{slugs[:ver]}"].join('/')}" }]
+      end
+
+      def create_sections(map)
+        Infobar(total: sections.size)
+        sections.values.each do |section|
+          infobar.progress(
+            message: " Section #{section.name.to_s.inspect} %c/%t in %te ETA %e @%E ",
+            force: true,
+          )
+          @only =~ section.name or next if @only
+
+          map = get_section_data(map, section)
+        end
+        infobar.finish message: ' %t sections created in %te, completed @%E '
+        infobar.newline
+        self
+      end
+
+      def create_assets
+        Infobar(total: config.swagger_assets.size)
+        config.each_swagger_asset do |src, dst|
+          infobar.progress(
+            message: " Asset #{File.basename(src).inspect} %c/%t in %te ETA %e @%E ",
+            force: true,
+          )
+          mkdir_p File.dirname(dst)
+          cp Betterdocs.rails.root.join(src), dst
+        end
+        infobar.finish message: ' %t assets created in %te, completed @%E '
+        infobar.newline
+        self
+      end
+
+      def create_swagger(map, dirname)
+        name = 'swagger.json'
+        cd dirname do
+          infobar.puts color(40, 'Creating swagger.')
+          json = JSON.pretty_generate(map)
+          render_to(name, json)
+        end
+        self
+      end
+
+      def fail_while_rendering(exception)
+        message = color(
+          231,
+          on_color(124, " *** ERROR #{exception.class}: #{exception.message.inspect} ***")
+        )
+        infobar.puts message
+        exit 1
+      end
+
+      def add_param(hash, name, param_in, required = false, type = nil, description = '', schema = nil)
+        hash[:parameters] ||= []
+        p = { in: param_in, required: required, description: description, name: name }
+        p[:schema] = { type: type } unless type.nil?
+        p[:schema] = schema unless schema.nil?
+        hash[:parameters].push(p)
+        hash
+      end
+
+      def add_default_list_params(hash)
+        p = add_param(hash, 'page', 'query', false, 'integer')
+        add_param(p, 'per_page', 'query', false, 'integer')
+      end
+
+      def get_list_response_wrapper_schema
+        {
+          type: 'object',
+          properties: {
+            total_entries: { type: 'integer' },
+            offset: { type: 'integer' },
+            total_pages: { type: 'integer' },
+            current_page: { type: 'integer' },
+            per_page: { type: 'integer' },
+          },
+          required: %w[total_entries offset current_page per_page total_pages data],
+        }
+      end
+
+      def get_param_value_type(value)
+        case value
+        when String then 'string'
+        when Integer then 'integer'
+        when TrueClass, FalseClass then 'boolean'
+        when Float then 'number'
+        when Array then 'array'
+        else 'object'
+        end
+      end
+
+      def get_path_param_slug_type(slug)
+        return 'integer' if /\A[0-9]+\z/.match(slug)
+
+        'string'
+      end
+
+      def add_error_envelope_schema(definitions)
+        definitions['ErrorEnvelope'] = {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            status: { type: 'string' },
+            status_code: { type: 'integer' },
+            reason: { type: 'string' },
+            backtrace: { type: 'array', items: { type: 'string' } },
+            message: { type: 'string' },
+            errors: { type: 'object' },
+            links: { type: 'array', items: { type: 'string' } },
+          },
+          required: %w[name status status_code reason backtrace message links],
+        }
+      end
+
+      def get_error_envelope_schema_ref
+        { schema: get_schema_ref('ErrorEnvelope') }
+      end
+
+      def get_request_url_slugs(request)
+        slugs = %r{
+          (?<method>GET|POST|PUT|DELETE|OPTIONS)\s+
+          (?<protocol>https?)://
+          (?<host>[a-z.]+)/
+          (?<lang>[a-z]{2})/api_
+          (?<ver>v[0-9]+)/
+          (?<path>[\w/]+\.json?)
+        }x.match(request).named_captures.transform_keys(&:to_sym)
+        slugs[:params] = []
+        split = slugs[:path].split('/')
+        path_cmp = split.map.with_index do |cmp, i|
+          unless i.even?
+            suffix = cmp['.json'] || ''
+            name = "#{split[i - 1]}_id"
+            cmp = "{#{name}}#{suffix}"
+            param = { name: name, type: get_path_param_slug_type(cmp.gsub('.json', '')) }
+            slugs[:params].push(param)
+          end
+          cmp
+        end
+        slugs[:method] = slugs[:method].downcase
+        slugs[:path] = "/#{path_cmp.join('/')}"
+        slugs
+      end
+
+      def get_request_definition(params)
+        schema = { type: 'object', properties: {}, required: [] }
+        params.each do |param|
+          schema[:properties][param.name] = get_schema(param.types, nil, param.description)
+          schema[:required].push(param.name) if param.required == true || param.required == 'yes'
+        end
+        schema
+      end
+
+      def get_name(title)
+        /([\w\s]+)/.match(title)[1]
+      end
+
+      def get_type(types)
+        type = types
+        nullable = false
+        if types.instance_of? Array
+          case types.length
+          when 0
+            type = nil
+          when 1
+            type = types[0]
+          else
+            types.each do |t|
+              if t == 'null'
+                nullable = true
+              else
+                type = t
+              end
+            end
+          end
+        end
+        unless %w[integer number string boolean array object].include?(type)
+          puts "Warning: invalid type #{type || 'nil'}"
+        end
+        [type, nullable]
+      end
+
+      def get_deprecated_from_description(description)
+        description.include?('DEPRECATED')
+      end
+
+      def get_schema(types, sub_cls, description)
+        type, nullable = get_type(types)
+        deprecated = get_deprecated_from_description(description)
+        res = { description: description, type: type, nullable: nullable, deprecated: deprecated }
+        case type
+        when 'array'
+          items = { type: 'string' }
+          items = get_schema_ref(sub_cls) if sub_cls
+          res[:items] = items
+        when 'object'
+          res = get_schema_ref(sub_cls) if sub_cls
+          res[:description] = description
+          res[:deprecated] = deprecated
+        end
+        res[:nullable] = true if nullable
+        res
+      end
+
+      def get_dto_name(representer)
+        representer&.name&.demodulize
+      end
+
+      def add_links_definition(definitions, cls, value)
+        definition = initialise_definition(definitions, cls)
+        definition[:properties][:links] ||= {
+          type: 'array',
+          nullable: false,
+          items: {
+            type: 'object',
+            properties: {
+              rel: { type: 'string', enum: [] },
+              href: { type: 'string' },
+            },
+            required: %w[rel href],
+          },
+        }
+        enum = definition[:properties][:links][:items][:properties][:rel][:enum]
+        enum.push(value) unless enum.include?(value)
+      end
+
+      def initialise_definition(definitions, cls)
+        definitions[cls] ||= { type: 'object', properties: {} }
+      end
+
+      def add_response_schema(definitions, response)
+        return nil unless response.full?
+
+        subs = {}
+        resp_cls = get_dto_name(response.representer)
+        (response.full?(:properties) || []).each do |p|
+          subs[p.full_name] = p.sub_representer? if p.sub_representer?
+          sub_cls = get_dto_name(subs[p.nesting_name])
+          cls = sub_cls || resp_cls
+          definition = initialise_definition(definitions, cls)
+          definition[:properties][p.public_name] = get_schema(p.types, get_dto_name(p.sub_representer?), p.description)
+        end
+        (response.full?(:links) || []).each do |l|
+          sub_cls = get_dto_name(subs[l.nesting_name])
+          add_links_definition(definitions, sub_cls || resp_cls, l.public_name)
+        end
+        get_schema_ref(resp_cls)
+      end
+
+      def get_schema_ref(name)
+        {
+          "$ref": "#/components/schemas/#{name}",
+        }
+      end
+
+      def add_required_to_definitions(definitions)
+        definitions.each do |def_key, d|
+          req = d[:properties].select { |_k, v| v.key?(:nullable) }.keys
+          definitions[def_key][:required] = req unless req.empty?
+        end
+      end
+
+      def add_body(definitions, params, action, name)
+        if action.json_params.full?
+          payload_name = "#{name.titleize.gsub(/\s/, '')}Request"
+          definitions[payload_name] = get_request_definition(action.json_params.values)
+          params[:requestBody] = wrap_content_object({ schema: get_schema_ref(payload_name) }, "#{name} Request")
+        end
+      end
+
+      def add_path_params(params, from_path)
+        from_path.each do |param|
+          add_param(params, param[:name], 'path', true, param[:type], param[:name])
+        end
+      end
+
+      def add_query_params(params, from_query, is_a_list)
+        from_query.each do |param|
+          add_param(params, param.name, 'query', param.required, get_param_value_type(param.value),
+                    param.description)
+        end
+        add_default_list_params(params) if is_a_list
+      end
+
+      def wrap_content_object(object, description)
+        { content: { "application/json": object }, description: description }
+      end
+
+      def add_example(obj, name, example)
+        obj[:examples] ||= {}
+        obj[:examples][name] = { value: example }
+      end
+
+      def get_section_data(map, section)
+        section.each do |action|
+          name = get_name(action.title)
+          p = { description: action.description, summary: name }
+          is_a_list = action.response.data.instance_of?(ApiTools::ResultSet)
+          slugs = get_request_url_slugs(action.request)
+          add_path_params(p, slugs[:params])
+          add_query_params(p, action.params.values, is_a_list)
+          add_body(map[:components][:schemas], p, action, name)
+          item = add_response_schema(map[:components][:schemas], action.response)
+          schema = item
+          if is_a_list
+            list = get_list_response_wrapper_schema
+            list[:properties][:data] = { type: 'array', items: item }
+            schema = list
+          end
+          ok = { schema: schema }
+          unless action.response.nil?
+            add_example(ok, 'example', JSON.parse(JSON.pretty_generate(action.response, quirks_mode: true)))
+          end
+          p[:responses] =
+            { "200": wrap_content_object(ok, 'OK'),
+              default: wrap_content_object(get_error_envelope_schema_ref, 'Error') }
+          wrapped = {}
+          wrapped = map[slugs[:path]] if map.key?(slugs[:path])
+          wrapped[slugs[:method]] = p
+          map[:paths][slugs[:path]] = wrapped
+        end
+        add_required_to_definitions(map[:components][:schemas])
+        map
+      end
+
+      def render_to(filename, content)
+        File.open(filename, 'w') do |output|
+          output.write(content)
+        end
+        self
+      rescue StandardError => e
+        fail_while_rendering(e)
+      end
+
+      def prepare_dir(dirname)
+        dirname.present? or raise ArgumentError,
+                                  "#{dirname.inspect} should be an explicite output dirname"
+        begin
+          stat = File.stat(dirname)
+          if stat.directory?
+            rm_rf Dir[dirname.to_s + '/**/*']
+          else
+            raise ArgumentError, "#{dirname.inspect} is not a directory"
+          end
+        rescue Errno::ENOENT
+        end
+        mkdir_p dirname.to_s
+        self
+      end
+    end
+  end
+end

data/lib/betterdocs/generator/swagger_static/index.html

@@ -0,0 +1,66 @@
+<!-- HTML for static distribution bundle build -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Swagger UI</title>
+
+    <link
+      rel="stylesheet"
+      href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.8.1/swagger-ui.css"
+      type="text/css"
+      charset="UTF-8"
+    />
+    <style>
+      html {
+        box-sizing: border-box;
+        overflow: -moz-scrollbars-vertical;
+        overflow-y: scroll;
+      }
+
+      *,
+      *:before,
+      *:after {
+        box-sizing: inherit;
+      }
+
+      body {
+        margin: 0;
+        background: #fafafa;
+      }
+    </style>
+  </head>
+
+  <body>
+    <div id="swagger-ui"></div>
+
+    <script
+      src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.8.1/swagger-ui-bundle.js"
+      charset="UTF-8"
+    ></script>
+    <script
+      src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.8.1/swagger-ui-standalone-preset.js"
+      charset="UTF-8"
+    ></script>
+    <script>
+      window.onload = function () {
+        fetch("./swagger.json")
+          .then(resp => resp.json())
+          .then(spec => {
+            const ui = SwaggerUIBundle({
+              spec: spec,
+              dom_id: "#swagger-ui",
+              deepLinking: true,
+              presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIStandalonePreset,
+              ],
+              plugins: [SwaggerUIBundle.plugins.DownloadUrl],
+              layout: "BaseLayout",
+            });
+            window.ui = ui;
+          });
+      };
+    </script>
+  </body>
+</html>

data/lib/betterdocs/global.rb

@@ -27,7 +27,7 @@ module Betterdocs
           platform_host host
           __send__("#{prefix}_host", host)
         else
-          [ __send__("#{prefix}_protocol"), __send__("#{prefix}_host") ] * '://'
+          [__send__("#{prefix}_protocol"), __send__("#{prefix}_host")].join('://')
         end
       end
 
@@ -41,7 +41,7 @@ module Betterdocs
 
       dsl_accessor :api_protocol do platform_protocol end     # Protocol the API understands
 
-      dsl_accessor :api_host   do platform_host end           # Hostname of the API (eventuallly with port number)
+      dsl_accessor :api_host do platform_host end # Hostname of the API (eventuallly with port number)
 
       def api_url(url = nil)
         handle_url(:api, url)
@@ -55,7 +55,7 @@ module Betterdocs
         handle_url(:asset, url)
       end
 
-      dsl_accessor :api_default_format,  'json'
+      dsl_accessor :api_default_format, 'json'
 
       def api_base_url
         "#{api_protocol}://#{api_host}/#{api_prefix}"
@@ -65,9 +65,11 @@ module Betterdocs
         { protocol: api_protocol, host: api_host, format: api_default_format }
       end
 
-      dsl_accessor :templates_directory                     # Template directory, where customised templates live if any exist
+      dsl_accessor :templates_directory # Template directory, where customised templates live if any exist
 
-      dsl_accessor :output_directory,    'api_docs'         # Output directory, where the api docs are created
+      dsl_accessor :output_directory, 'api_docs' # Output directory, where the api docs are created
+
+      dsl_accessor :swagger_output_directory, 'swagger_docs' # Output directory, where the swagger docs are created
 
       dsl_accessor :publish_git                             # URL to the git repo to which the docs are pushed
 
@@ -89,6 +91,17 @@ module Betterdocs
         @assets
       end
 
+      def swagger_assets=(hash)
+        @swagger_assets&.clear
+        swagger_assets(hash)
+      end
+
+      def swagger_assets(hash = nil)
+        @swagger_assets ||= {}
+        hash&.each { |path, to| swagger_asset path, to: to }
+        @swagger_assets
+      end
+
       # Defines an asset for the file at +path+. If +to+ was given it will be
       # copied to this path (it includes the basename) below
       # +templates_directory+ in the output, otherwise it will be copied
@@ -100,14 +113,25 @@ module Betterdocs
         elsif to == :root
           @assets[path.to_s] = to
         else
-          raise ArgumentError, "keyword argument to needs to be a string or :root"
+          raise ArgumentError, 'keyword argument to needs to be a string or :root'
+        end
+      end
+
+      def swagger_asset(path, to: :root)
+        @swagger_assets ||= {}
+        if destination = to.ask_and_send(:to_str)
+          @swagger_assets[path.to_s] = destination
+        elsif to == :root
+          @swagger_assets[path.to_s] = to
+        else
+          raise ArgumentError, 'keyword argument to needs to be a string or :root'
         end
       end
 
       # Maps the assets original source path to its destination path in the
       # output by yielding to every asset's source/destination pair.
       def each_asset
-        for (path, destination) in assets
+        assets.each do |(path, destination)|
           path = path.to_s
           if destination == :root
             yield path, File.join(output_directory.to_s, File.basename(path))
@@ -117,6 +141,17 @@ module Betterdocs
         end
       end
 
+      def each_swagger_asset
+        swagger_assets.each do |(path, destination)|
+          path = path.to_s
+          if destination == :root
+            yield path, File.join(swagger_output_directory.to_s, File.basename(path))
+          else
+            yield path, File.join(swagger_output_directory.to_s, destination.to_str)
+          end
+        end
+      end
+
       def configuration_file
         cc.betterdocs
       rescue ComplexConfig::ConfigurationFileMissing
@@ -192,7 +227,8 @@ module Betterdocs
 
       def url_for(options = {})
         Betterdocs.rails.application.routes.url_for(
-          options | Betterdocs::Global.config.api_url_options)
+          options | Betterdocs::Global.config.api_url_options
+        )
       end
     end
   end

data/lib/betterdocs/tasks/doc.rake

@@ -1,6 +1,6 @@
 namespace :doc do
-  desc "Create the API documentation"
-  task :api => :'doc:api:sandbox' do
+  desc 'Create the API documentation'
+  task api: :'doc:api:sandbox' do
     Betterdocs::Global.config do |config|
       Betterdocs::Generator::Markdown.new(only: ENV['ONLY']).generate
       cd config.output_directory do
@@ -15,39 +15,46 @@ namespace :doc do
 
   namespace :api do
     desc 'Let database transactions run in a sandboxed environment'
-    task :sandbox => [:'doc:set_betterdocs_env', :environment] do
-
+    task sandbox: %i[doc:set_betterdocs_env environment] do
       ActiveRecord::Base.connection.begin_db_transaction
       at_exit do
-         ActiveRecord::Base.connection.rollback_db_transaction
+        ActiveRecord::Base.connection.rollback_db_transaction
       end
     end
 
-    desc "Push the newly created API documentation to the remote git repo"
-    task :push => :api do
+    desc 'Create the API swagger documentation'
+    task swagger: :'doc:api:sandbox' do
       Betterdocs::Global.config do |config|
-        config.publish_git or fail "Configure a git repo as publish_git to publish to"
+        Betterdocs::Generator::Swagger.new(only: ENV['ONLY']).generate
+        cd config.swagger_output_directory do
+          File.open('.gitignore', 'w') { |ignore| ignore.puts config.ignore }
+        end
+      end
+    end
+
+    desc 'Push the newly created API documentation to the remote git repo'
+    task push: :api do
+      Betterdocs::Global.config do |config|
+        config.publish_git or raise 'Configure a git repo as publish_git to publish to'
         cd config.output_directory do
-          File.directory?('.git') or sh "git init"
-          sh "git remote rm publish_git || true"
+          File.directory?('.git') or sh 'git init'
+          sh 'git remote rm publish_git || true'
           sh "git remote add publish_git #{config.publish_git}"
-          sh "git add -A"
+          sh 'git add -A'
           sh 'git commit -m "Add some more changes to API documentation" || true'
           sh 'git push -f publish_git master'
         end
       end
     end
 
-    desc "Publish the newly created API documentation"
-    task :publish => [ :push ]
+    desc 'Publish the newly created API documentation'
+    task publish: [:push]
 
-    desc "Publish and view the newly created API documentation"
-    task :view => :publish do
+    desc 'Publish and view the newly created API documentation'
+    task view: :publish do
       Betterdocs::Global.config do |config|
         url = config.publish_git
-        if url !~ /\Ahttps?:/
-          url.sub!(/.*?([^@]*):/, 'http://\1/')
-        end
+        url.sub!(/.*?([^@]*):/, 'http://\1/') if url !~ /\Ahttps?:/
         sh "open #{url.inspect}"
       end
     end

data/lib/betterdocs/version.rb

@@ -1,6 +1,6 @@
 module Betterdocs
   # Betterdocs version
-  VERSION         = '0.7.1'
+  VERSION         = '0.8.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: betterdocs
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - betterplace Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-06-01 00:00:00.000000000 Z
+date: 2021-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gem_hadar
@@ -190,6 +190,7 @@ extra_rdoc_files:
 - lib/betterdocs/dsl/result/property.rb
 - lib/betterdocs/generator/config_shortcuts.rb
 - lib/betterdocs/generator/markdown.rb
+- lib/betterdocs/generator/swagger.rb
 - lib/betterdocs/global.rb
 - lib/betterdocs/json_params_representer.rb
 - lib/betterdocs/json_params_representer_collector.rb
@@ -209,6 +210,7 @@ files:
 - ".rspec"
 - ".semaphore/semaphore.yml"
 - ".tool-versions"
+- ".vscode/settings.json"
 - COPYING
 - Gemfile
 - LICENSE
@@ -239,6 +241,8 @@ files:
 - lib/betterdocs/generator/markdown.rb
 - lib/betterdocs/generator/markdown/templates/README.md.erb
 - lib/betterdocs/generator/markdown/templates/section.md.erb
+- lib/betterdocs/generator/swagger.rb
+- lib/betterdocs/generator/swagger_static/index.html
 - lib/betterdocs/global.rb
 - lib/betterdocs/json_params_representer.rb
 - lib/betterdocs/json_params_representer_collector.rb