betterdocs 0.2.0

data/README.md

@@ -0,0 +1,124 @@
+Betterdocs API Documentation
+============================
+
+[![Code Climate](https://codeclimate.com/repos/51128561f3ea0022cc027f31/badges/2a9719de54628d821871/gpa.png)](https://codeclimate.com/repos/51128561f3ea0022cc027f31/feed)
+
+DESCRIPTION
+-----------
+
+This library can be used to document a rails based API.
+
+LICENSE
+-------
+
+Apache License Version 2.0, see also the COPYING file.
+
+USAGE EXAMPLES
+--------------
+
+These are some examples. Note that they are neither complete, nor work out of the box.
+
+This api generator requires that you follow the [representer pattern](http://nicksda.apotomo.de/2011/12/ruby-on-rest-introducing-the-representer-pattern/) to decorate the objects you want to render. Betterdocs comes with it's own representer support baked in.
+
+## Controller
+
+    class ThingsController < ApplicationController
+      # :nocov: Documentation
+      doc :action do
+        section     :things_list
+        title       'A List of things ⇄ [Details](things_details.md)'
+        description to <<-end
+          This action shows a list of things. **Markdown** can be used.
+        end
+
+        param :order do
+          description to <<-end
+            Optional parameter to order the list.
+          end
+          required    no
+          value       'created_at:ASC'
+        end
+
+        response do
+          generate_fake_result_with_representer 
+        end
+      end
+      # :nocov:
+      def index
+        render json: real_result_with_representer 
+      end
+
+      # :nocov: Documentation
+      doc :action do
+        section     :things_details
+        title       'Things Details ⇄ [List](things_list.md)'
+        description to <<-end
+          The details of a thing. You must give an id for the thing
+        end
+
+        param :thing_id do
+          description 'The id of the thing you want to see. Required.'
+          required    yes # this is the default
+          value       38
+        end
+
+        response do
+          generate_fake_details_response_with_representer
+        end
+      end
+      # :nocov:
+      def show
+        render json: real_result_with_representer 
+      end
+    end
+
+## Representer
+
+Betterdocs comes with its own representer class. It is not documented
+yet but works kind of like [ROAR](https://github.com/apotonick/roar).
+
+    module ThingsRepresenter
+
+      extend ActiveSupport::Concern
+      include Betterdocs::Representer
+
+      property :microfleem_count, if: -> { has_microfleems? }, as: :number_of_fleems do
+        description 'If we have microfleems, return the count'
+        types       Integer
+        example     '5000'
+      end
+
+      property :title, as: :name do
+        description to <<-end
+          Represent the internal field "title" as the name of the thing
+        end
+        types       String
+        example     'my_name'
+      end
+
+      link :self do
+        description to <<-end
+          Link to this resource itself
+          (<a href="opinion_details.md">things details</a>)
+        end
+        url { thing_url(id) }
+      end
+    end
+
+AUTHORS
+-------
+Florian Frank <flori@ping.de>
+
+TODO
+----
+- Implement some kind of scheme for versioning or at least better commit messages;
+  we also may want to keep other peoples commits if possible (how?).
+- Refactor configuration to avoid singleton antipattern
+- Create method in generator that considers a given string to be markdown
+  formatted and compiles it to html (as a work around to put multiline
+  descriptions inside of html tables in a markdown)
+- Display enums as possible values in representers
+- Automatically document error result documents
+- Use private flag action/controller to skip docu creation by default. Make it
+  configurable to create private API as well.
+

data/Rakefile

@@ -0,0 +1,25 @@
+# vim: set filetype=ruby et sw=2 ts=2:
+
+require 'gem_hadar'
+
+GemHadar do
+  name        'betterdocs'
+  author      'betterplace Developers'
+  email       'developers@betterplace.org'
+  homepage    "http://github.com/betterplace/#{name}"
+  summary     'Betterplace API documentation library'
+  description "This library provides tools to generate API documention for a web site's REST-ful JSON API."
+  test_dir    'spec'
+  ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage', '.rvmrc',
+    '.ruby-version', '.AppleDouble', 'tags', '.DS_Store', '.utilsrc', '.bundle'
+  readme      'README.md'
+  title       "#{name.camelize} -- "
+
+  dependency 'tins',           '~>1.3', '>=1.3.5'
+  dependency 'rails',          '>=3', '<5'
+  dependency 'term-ansicolor', '~>1.3'
+  development_dependency 'simplecov'
+  development_dependency 'rspec'
+end
+
+task :default => :spec

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/betterdocs.gemspec

@@ -0,0 +1,48 @@
+# -*- encoding: utf-8 -*-
+# stub: betterdocs 0.2.0 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "betterdocs"
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib"]
+  s.authors = ["betterplace Developers"]
+  s.date = "2016-03-30"
+  s.description = "This library provides tools to generate API documention for a web site's REST-ful JSON API."
+  s.email = "developers@betterplace.org"
+  s.extra_rdoc_files = ["README.md", "lib/betterdocs.rb", "lib/betterdocs/controller_collector.rb", "lib/betterdocs/dsl.rb", "lib/betterdocs/dsl/common.rb", "lib/betterdocs/dsl/controller.rb", "lib/betterdocs/dsl/controller/action.rb", "lib/betterdocs/dsl/controller/action/param.rb", "lib/betterdocs/dsl/controller/action/response.rb", "lib/betterdocs/dsl/controller/controller.rb", "lib/betterdocs/dsl/controller/controller_base.rb", "lib/betterdocs/dsl/json_params.rb", "lib/betterdocs/dsl/json_params/param.rb", "lib/betterdocs/dsl/json_type_mapper.rb", "lib/betterdocs/dsl/naming.rb", "lib/betterdocs/dsl/representer.rb", "lib/betterdocs/dsl/result.rb", "lib/betterdocs/dsl/result/collection_property.rb", "lib/betterdocs/dsl/result/link.rb", "lib/betterdocs/dsl/result/property.rb", "lib/betterdocs/generator/config_shortcuts.rb", "lib/betterdocs/generator/markdown.rb", "lib/betterdocs/global.rb", "lib/betterdocs/json_params_representer.rb", "lib/betterdocs/json_params_representer_collector.rb", "lib/betterdocs/mix_into_controller.rb", "lib/betterdocs/rake_tasks.rb", "lib/betterdocs/representer.rb", "lib/betterdocs/result_representer.rb", "lib/betterdocs/result_representer_collector.rb", "lib/betterdocs/section.rb", "lib/betterdocs/version.rb"]
+  s.files = [".codeclimate.yml", ".gitignore", ".rspec", ".travis.yml", "COPYING", "Gemfile", "LICENSE", "README.md", "Rakefile", "VERSION", "betterdocs.gemspec", "lib/betterdocs.rb", "lib/betterdocs/controller_collector.rb", "lib/betterdocs/dsl.rb", "lib/betterdocs/dsl/common.rb", "lib/betterdocs/dsl/controller.rb", "lib/betterdocs/dsl/controller/action.rb", "lib/betterdocs/dsl/controller/action/param.rb", "lib/betterdocs/dsl/controller/action/response.rb", "lib/betterdocs/dsl/controller/controller.rb", "lib/betterdocs/dsl/controller/controller_base.rb", "lib/betterdocs/dsl/json_params.rb", "lib/betterdocs/dsl/json_params/param.rb", "lib/betterdocs/dsl/json_type_mapper.rb", "lib/betterdocs/dsl/naming.rb", "lib/betterdocs/dsl/representer.rb", "lib/betterdocs/dsl/result.rb", "lib/betterdocs/dsl/result/collection_property.rb", "lib/betterdocs/dsl/result/link.rb", "lib/betterdocs/dsl/result/property.rb", "lib/betterdocs/generator/config_shortcuts.rb", "lib/betterdocs/generator/markdown.rb", "lib/betterdocs/generator/markdown/templates/README.md.erb", "lib/betterdocs/generator/markdown/templates/section.md.erb", "lib/betterdocs/global.rb", "lib/betterdocs/json_params_representer.rb", "lib/betterdocs/json_params_representer_collector.rb", "lib/betterdocs/mix_into_controller.rb", "lib/betterdocs/rake_tasks.rb", "lib/betterdocs/representer.rb", "lib/betterdocs/result_representer.rb", "lib/betterdocs/result_representer_collector.rb", "lib/betterdocs/section.rb", "lib/betterdocs/tasks/doc.rake", "lib/betterdocs/version.rb", "spec/controller_dsl_spec.rb", "spec/generator/markdown_spec.rb", "spec/json_params_representer_spec.rb", "spec/json_type_mapper_spec.rb", "spec/result_representer_dsl_spec.rb", "spec/result_representer_spec.rb", "spec/spec_helper.rb"]
+  s.homepage = "http://github.com/betterplace/betterdocs"
+  s.rdoc_options = ["--title", "Betterdocs -- ", "--main", "README.md"]
+  s.rubygems_version = "2.5.1"
+  s.summary = "Betterplace API documentation library"
+  s.test_files = ["spec/controller_dsl_spec.rb", "spec/generator/markdown_spec.rb", "spec/json_params_representer_spec.rb", "spec/json_type_mapper_spec.rb", "spec/result_representer_dsl_spec.rb", "spec/result_representer_spec.rb", "spec/spec_helper.rb"]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<gem_hadar>, ["~> 1.6.1"])
+      s.add_development_dependency(%q<simplecov>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_runtime_dependency(%q<tins>, [">= 1.3.5", "~> 1.3"])
+      s.add_runtime_dependency(%q<rails>, ["< 5", ">= 3"])
+      s.add_runtime_dependency(%q<term-ansicolor>, ["~> 1.3"])
+    else
+      s.add_dependency(%q<gem_hadar>, ["~> 1.6.1"])
+      s.add_dependency(%q<simplecov>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<tins>, [">= 1.3.5", "~> 1.3"])
+      s.add_dependency(%q<rails>, ["< 5", ">= 3"])
+      s.add_dependency(%q<term-ansicolor>, ["~> 1.3"])
+    end
+  else
+    s.add_dependency(%q<gem_hadar>, ["~> 1.6.1"])
+    s.add_dependency(%q<simplecov>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<tins>, [">= 1.3.5", "~> 1.3"])
+    s.add_dependency(%q<rails>, ["< 5", ">= 3"])
+    s.add_dependency(%q<term-ansicolor>, ["~> 1.3"])
+  end
+end

data/lib/betterdocs.rb

@@ -0,0 +1,27 @@
+require 'tins/xt'
+require 'rails'
+
+module Betterdocs
+  class << self
+    def rails
+      ::Rails
+    end
+
+    alias trait proc
+    public :trait
+  end
+end
+
+require 'betterdocs/version'
+require 'betterdocs/dsl'
+require 'betterdocs/result_representer'
+require 'betterdocs/result_representer_collector'
+require 'betterdocs/controller_collector'
+require 'betterdocs/json_params_representer_collector'
+require 'betterdocs/json_params_representer'
+require 'betterdocs/global'
+require 'betterdocs/section'
+require 'betterdocs/mix_into_controller'
+require 'betterdocs/generator/config_shortcuts'
+require 'betterdocs/generator/markdown'
+require 'betterdocs/rake_tasks'

data/lib/betterdocs/controller_collector.rb

@@ -0,0 +1,50 @@
+module Betterdocs
+  class ControllerCollector
+    def initialize
+      @actions    = {}
+      @element    = nil
+      @controller = nil
+    end
+
+    attr_accessor :controller
+
+    attr_writer :element
+
+    def actions
+      @actions.values.reject(&:private)
+    end
+
+    def action(action_name)
+      action_name = action_name.to_sym
+      @actions[action_name]
+    end
+
+    def section
+      @controller.ask_and_send(:section)
+    end
+
+    def add_element(klass, type, &block)
+      element = build_element(klass, type, &block)
+      element.add_to_collector(self)
+    end
+
+    def configure_current_element(action_name)
+      if @element
+        @element.configure_for_action(action_name)
+        @actions[action_name] = @element
+      end
+      @element = nil
+      self
+    end
+
+    def to_s
+      ([ @controller, '=' * 79, actions * ("-" * 79 + "\n"), '' ]) * "\n"
+    end
+
+    private
+
+    def build_element(klass, type, &block)
+      Dsl::Controller.const_get(type.to_s.camelcase).new(klass, &block)
+    end
+  end
+end

data/lib/betterdocs/dsl.rb

@@ -0,0 +1,9 @@
+module Betterdocs
+  module Dsl
+  end
+end
+
+require 'betterdocs/dsl/naming'
+require 'betterdocs/dsl/controller'
+require 'betterdocs/dsl/result'
+require 'betterdocs/dsl/json_params'

data/lib/betterdocs/dsl/common.rb

@@ -0,0 +1,26 @@
+module Betterdocs
+  module Dsl
+    module Common
+      extend Tins::Constant
+
+      constant :yes, true
+
+      constant :no,  false
+
+      def set_context(context)
+        @__context__ = context
+        self
+      end
+
+      private
+
+      def method_missing(name, *a, &b)
+        if @__context__
+          @__context__.__send__(name, *a, &b)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/betterdocs/dsl/controller.rb

@@ -0,0 +1,9 @@
+module Betterdocs
+  module Dsl
+    module Controller
+    end
+  end
+end
+
+require 'betterdocs/dsl/controller/action'
+require 'betterdocs/dsl/controller/controller'

data/lib/betterdocs/dsl/controller/action.rb

@@ -0,0 +1,126 @@
+require 'betterdocs/dsl/controller/controller_base'
+require 'betterdocs/dsl/common.rb'
+
+class Betterdocs::Dsl::Controller::Action < Betterdocs::Dsl::Controller::ControllerBase
+  require 'betterdocs/dsl/controller/action/param'
+  require 'betterdocs/dsl/controller/action/response'
+
+  dsl_accessor :action
+
+  alias name action
+
+  dsl_accessor :title do "All about: #{action}" end
+
+  dsl_accessor :section do
+    controller.docs.controller.full?(:section) || :misc
+  end
+
+  dsl_accessor :action_method
+
+  dsl_accessor :http_method do
+    case action
+    when :show, :index
+      :GET
+    when :update
+      :PUT
+    when :destroy
+      :DELETE
+    when :create
+      :POST
+    else
+      raise ArgumentError, "Cannot automatically derive http_method for"\
+        " #{name.inspect}, specify manually"
+    end
+  end
+
+  dsl_accessor :params do {} end
+
+  dsl_accessor :json_params_representer
+
+  def json_params_like(klass)
+    json_params_representer klass.docs
+    self
+  end
+
+  def json_params
+    json_params_representer.full?(:params)
+  end
+
+  def json_params_example_json
+    if params = json_params_representer.full?(:params)
+      data = {}
+      params.each_with_object(data) do |(name, param), d|
+        d[name] = param.value
+      end
+      JSON.pretty_generate(JSON.load(JSON.dump(data)), quirks_mode: true) # sigh, don't ask…
+    end
+  end
+
+  dsl_accessor :private, false
+
+  def param(name, &block)
+    name = name.to_sym
+    if block
+      param = Betterdocs::Dsl::Controller::Action::Param.new(name, &block)
+      param.value or param.value params.size + 1
+      params[name] = param
+    else
+      params[name]
+    end
+  end
+
+  dsl_accessor :responses do {} end
+
+  def response(name = :default, &block)
+    if block
+      responses[name] = Betterdocs::Dsl::Controller::Action::Response.new(
+        name, &block
+      ).set_context(self)
+    else
+      responses[name]
+    end
+  end
+
+  dsl_accessor :description, 'TODO'
+
+  def configure_for_action(action_name)
+    action action_name
+    action_method controller.instance_method(action_name)
+  end
+
+  def include_params(callee)
+    instance_eval(&callee)
+  end
+
+  def url
+    url_params = params.select { |_, param| param.use_in_url? }
+    Betterdocs.rails.application.routes.url_for(
+      {
+        controller: controller.name.underscore.sub(/_controller\z/, ''),
+        action:     action,
+      } | url_params | Betterdocs::Global.config.api_url_options
+    )
+  end
+
+  def request
+    "#{http_method.to_s.upcase} #{url}"
+  end
+
+  def to_s
+    (
+      [ request, '' ] +
+      [ inspect, '' ] +
+      params.map { |name, param|
+        "#{name}(=#{param.value}): #{param.description}"
+      } + [ '', description, '', action_method.source_location * ':', '' ]
+    ) * "\n"
+  end
+
+  def inspect
+    "#{controller}##{action}(#{params.keys * ', '})"
+  end
+
+  def add_to_collector(collector)
+    collector.element = self
+  end
+end