apidoco_dsl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b2ac5c3c67fb00766a4f2b0e950d5a78fcb3856ca7aa326bda1190178ed4782b
+  data.tar.gz: c31cbdb3a36888731cfc8de10ff1126e745ba2fec09184f021655a81cd0dd7c3
+SHA512:
+  metadata.gz: 63e799515b3cf792abed9424abee6afca94165a84851290ef7dafa7feb9dadb8915e765bb06e143453e26965a3aa87f89c80335f91be8f949bad94ff97193493
+  data.tar.gz: c668eb909680132161998c93c0d47e4e1bf0c98a402690af54f3a109ed88cbf7b16f11cd77209be3c3a6201c023abce1e45ba0409b58d68ba2eff0575b946e65

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.5.1
+before_install: gem install bundler -v 2.0.2

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in apidoco_dsl.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,166 @@
+PATH
+  remote: .
+  specs:
+    apidoco_dsl (0.1.0)
+      apidoco (~> 1.5)
+      kramdown
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (6.0.3.1)
+      actionpack (= 6.0.3.1)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.0.3.1)
+      actionpack (= 6.0.3.1)
+      activejob (= 6.0.3.1)
+      activerecord (= 6.0.3.1)
+      activestorage (= 6.0.3.1)
+      activesupport (= 6.0.3.1)
+      mail (>= 2.7.1)
+    actionmailer (6.0.3.1)
+      actionpack (= 6.0.3.1)
+      actionview (= 6.0.3.1)
+      activejob (= 6.0.3.1)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (6.0.3.1)
+      actionview (= 6.0.3.1)
+      activesupport (= 6.0.3.1)
+      rack (~> 2.0, >= 2.0.8)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.0.3.1)
+      actionpack (= 6.0.3.1)
+      activerecord (= 6.0.3.1)
+      activestorage (= 6.0.3.1)
+      activesupport (= 6.0.3.1)
+      nokogiri (>= 1.8.5)
+    actionview (6.0.3.1)
+      activesupport (= 6.0.3.1)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.0.3.1)
+      activesupport (= 6.0.3.1)
+      globalid (>= 0.3.6)
+    activemodel (6.0.3.1)
+      activesupport (= 6.0.3.1)
+    activerecord (6.0.3.1)
+      activemodel (= 6.0.3.1)
+      activesupport (= 6.0.3.1)
+    activestorage (6.0.3.1)
+      actionpack (= 6.0.3.1)
+      activejob (= 6.0.3.1)
+      activerecord (= 6.0.3.1)
+      marcel (~> 0.3.1)
+    activesupport (6.0.3.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    angularjs-rails (1.6.8)
+    apidoco (1.5.4)
+      angularjs-rails
+      rails (>= 4.0.0)
+    builder (3.2.4)
+    concurrent-ruby (1.1.6)
+    crass (1.0.6)
+    diff-lcs (1.3)
+    erubi (1.9.0)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
+    i18n (1.8.2)
+      concurrent-ruby (~> 1.0)
+    kramdown (2.2.1)
+      rexml
+    loofah (2.5.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (0.3.3)
+      mimemagic (~> 0.3.2)
+    method_source (1.0.0)
+    mimemagic (0.3.5)
+    mini_mime (1.0.2)
+    mini_portile2 (2.4.0)
+    minitest (5.14.1)
+    nio4r (2.5.2)
+    nokogiri (1.10.9)
+      mini_portile2 (~> 2.4.0)
+    rack (2.2.2)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (6.0.3.1)
+      actioncable (= 6.0.3.1)
+      actionmailbox (= 6.0.3.1)
+      actionmailer (= 6.0.3.1)
+      actionpack (= 6.0.3.1)
+      actiontext (= 6.0.3.1)
+      actionview (= 6.0.3.1)
+      activejob (= 6.0.3.1)
+      activemodel (= 6.0.3.1)
+      activerecord (= 6.0.3.1)
+      activestorage (= 6.0.3.1)
+      activesupport (= 6.0.3.1)
+      bundler (>= 1.3.0)
+      railties (= 6.0.3.1)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    railties (6.0.3.1)
+      actionpack (= 6.0.3.1)
+      activesupport (= 6.0.3.1)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.20.3, < 2.0)
+    rake (10.5.0)
+    rexml (3.2.4)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.2)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.3)
+    sprockets (4.0.0)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    thor (1.0.1)
+    thread_safe (0.3.6)
+    tzinfo (1.2.7)
+      thread_safe (~> 0.1)
+    websocket-driver (0.7.2)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  apidoco_dsl!
+  bundler (~> 2.0)
+  rake (~> 10.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.0.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Steve Lewis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,268 @@
+# ApidocoDsl
+
+This gem provides a DSL wrapper around the excellent [Apidoco Gem](https://github.com/72pulses/apidoco) for Ruby on Rails projects. The DSL is heavily inspired by the one provided by [Apipie](https://github.com/Apipie/apipie-rails), but it was developed from scratch. In our opinion, the Apidoco system is more flexible, and it's output is prettier than Apipie. The one thing it was lacking was a good DSL to produce the JSON files that make up its documentation output. That's where this gem comes in. Instead of writing JSON files by hand, using this gem you can write your documentation directly in to your code _as code_, which is later parsed and converted into the JSON files that feed the Apidoco engine.
+
+## Compatibility with Apidoco
+
+This DSL gem was written against the 1.5.4 version of the Apidoco gem. Later versions of Apidoco may introduce breaking changes with this gem, but we'll do our best to keep it up to date. One important point with regards to compatibility is that this gem renders Apidoco's resource generator, (`rails g apidoco resource`), unnecessary, unless there really is certain documentation you'd rather write the raw JSON file for. Using this gem, documentation that you write into your code will automatically be placed in the right locations for the Apidoco engine.
+
+## Generating documentation
+
+Once you've written your documentation into your code, it has to be parsed and written out to the appropriate Apidoco directory in JSON format. This gem provides a generator for this purpose that is invoked this way:
+
+```bash
+rails g apidoco_dsl:documentation
+```
+
+## Writing Documentation
+
+### Where to write it
+
+As mentioned before, this gem allows you to write documentation for your code using code. There are a couple ways you can do this, depending upon the needs of your project and how much you want to intermingle your functional code with your documentation.
+
+#### Inline with the methods they document
+
+By including the ApidocoDsl module in to the classes you want to document, you can write your documentation in the same file with the code it documents:
+
+```ruby
+class MyApiController < ApplicationController
+  require 'apidoco_dsl'
+  extend ApidocoDsl
+
+  namespace "V1"
+  resource :widgets
+
+  api_doc do
+    ...
+  end
+  def show
+    ...
+  end
+end
+```
+
+#### In a separate class
+
+Unlike systems like Apipie, with Apidoco and this gem, there is no inherent programmatic link between documentation and the classes/methods being documented. Because of this, it is possible, (and perhaps even preferable), to define all of your documentation in locations and classes that are entirely separate from the code they document. You are free to organize your documentation files however it makes sense to you.
+
+```ruby
+module ApiDocs
+  class MyResource
+    extend ApidocoDsl
+    extend ActiveSupport::Concern
+
+    api_doc do
+      ...
+    end
+  end
+end
+```
+
+### The DSL
+
+At the most basic level, ApidocoDsl is used for writing documentation about the individual endpoints of your API. Doing so starts with defining an `api_doc` block. Below is a "full" doc block:
+
+```ruby
+api_doc do
+  published true
+  name "Do Something"
+  description "Does Something"
+  endpoint "/v1/do_something/"
+  http_method 'POST'
+  header({ 'Content-Type' => 'application/json', 'Authentication' => "Bearer <token>" })
+
+  param :thing1, type: 'String',  desc: 'The first thing', notes: "Introduced by the Cat In The Hat", required: true
+  param :thing2, type: 'Integer', desc: 'The second thing', notes: "Comes with Thing 1"
+
+  example_request do
+    {
+      thing1: "This is the first thing",
+      thing2: 42
+    }
+  end
+
+  example_response path: example_root + '/create_response.json'
+
+  returns code: :created do
+    property :thing_id, type: 'Integer', desc: "The thing's ID", notes: "Will be a number"
+    param_group :carrier_connection_response
+  end
+end
+```
+
+Note in the example above that `example_root` is a variable defined above this definition, and not actually part of the ApidocoDsl.
+
+Everything inside the block is considered documentation for the endpoint. It may be helpful to read the [Apidoco documentation](https://github.com/72pulses/apidoco), for context on some of these, but each method is described below.
+
+#### published
+
+Whether or not this documentation should be 'published', that is, visible on the documentation site. By default, documentation is _not_ published. Calling this method with an argument of `true`, will make it visible.
+
+#### name
+
+This is the name that will be displayed on the documentation page to identify this endpoint, both as a header and in the navigation. It can be anything you want, but obviously should actually identify the endpoint being documented. It takes a string.
+
+#### description
+
+A longer-form description of the endpoint. This method takes either a string _or_ a path argument. Given a string, it will simply display that string. Given a path, it will parse the provided file, (as Markdown), and use the result as the description for the endpoint.
+
+#### endpoint
+
+The URL for the endpoint being documented. It will be copied as is into the final documentation for the endpoint. By convention, any parameters provided in the endpoint url are preceded by colons, like this:
+
+`endpoint: "v1/customers/:id"`
+
+#### http_method
+
+Which HTTP method(s) to use when calling this endpoint. This is a string that will be passed, as-is to the final documentation. For endpoints that accept more than one method, (`PUT` or `PATCH`, for instance), separate them with pipes: `PUT|PATCH`.
+
+#### header
+
+What, if any sort of headers to include in the request to this endpoint. Common choices might be a `Content-Type` header or an `Authentication` header.
+
+#### param
+
+This method defines a param for this endpoint. It is discussed in more detail below.
+
+#### property
+
+Like a `param`, but generally used to define _responses_ rather than requests. Discussed in more detail below.
+
+#### param_group
+
+A param_group is used to, literally, group a set of params or properties together. This may be done for simple organizatonal reasons, but it is most useful for creating sets of parameters that can be reused in multiple endpoint definitions. Param groups are discussed in more detail below.
+
+#### example_request / example_response
+
+There are two ways to provide an example request or an example response for an endpoint. The first is to provide a block to the method itself, adding your example inside:
+
+```ruby
+example_request do
+  { "param1": "foo", "param2": "bar" }
+end
+```
+
+The hash will be automatically converted to JSON for presentation purposes.
+
+
+Alternatively, you can provide a `path` argument that points to a `json` file:
+
+```ruby
+  example_request path: "/examples/endpoint_request.json"
+```
+
+#### returns
+
+If your API endpoint returns any properties, the `returns` method allows you to specify what they are by identifying them as properties:
+
+```ruby
+returns do
+  property :response_1, type: "String", desc: "The first part of the response"
+  property :response_2, type: "Integer", desc:
+end
+```
+
+You can also specify a response `code`, whether or not the endpoint returns any other properties. If not specified, the `code` is 200.
+
+```ruby
+  returns code: 203 do
+    ...
+  end
+```
+
+### Params and Properties
+
+Describing which parameters your endpoints take and what properties they return is handled by the `param` and `property` methods respectively. These methods work the same way and are technically interchangeable. The only difference is that any defined properties
+are considered `required` by default.
+
+Here's an example param:
+
+```ruby
+  param :age, type: 'Integer', desc: "How old this person is.", notes: "Used for setting various interface options", validations: "Must be a positive integer.", required: true
+```
+
+A param/property takes the following attributes:
+
+#### name
+
+The name of the param/property is the first argument to the method and is always required. Note that it is a positional argument, not a kwarg.
+
+#### type
+
+A kwarg that describes the "type" of the parameter. If you provide a string, this value can be anything you want. It's also possible to pass any valid Ruby type, (String, Array, Hash, etc.), without enclosing it in a string. The `type` argument is required.
+
+#### desc
+
+An optional kwarg that takes a string describing the parameter. For the sake of formatting, it's best if the description is kept relatively short.
+
+#### notes
+
+An optional kwarg for providing additional context or information about a parameter. For the sake of formatting, it's best if the description is kept relatively short. Notes are an optional means of highlighting specific information about a parameter, (such as acceptable values), etc.
+
+#### validations
+
+An optional kwarg for adding a note about any validations present on the given parameter. For the sake of formatting, it's best if the validations argument is kept relatively short.
+
+#### required
+
+Whether or not this parameter is required. Take a boolean and defaults to `false` for a param and `true` for a property.
+
+### Param Groups
+
+Param groups allow you to define a set of parameters that can be shared between individual documentation blocks, reducing duplication. You define them by calling `def_param_group`:
+
+```ruby
+  def_param_group :my_group do
+    param :param1, type: "Integer", desc: "The first param"
+    param :param2, type: "Integer", desc: "The second param"
+  end
+```
+You can define params or properties inside of a param group just like you would inside of an `api_doc` block. To add a param group to a doc block, use the `param_group` method:
+
+```ruby
+  api_doc do
+    ...
+
+    param_group :my_group
+
+    ...
+
+    returns do
+      param_group :my_response_group
+    end
+  end
+```
+
+The `param_group` method takes a single argument, the name of the param group you want to invoke.
+
+Once a param group is defined, it can be used in _any_ documentation block, even those that are in a different source file. For that reason, it may be convenient to define your param groups in files separate from your api documentation itself.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'apidoco_dsl'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install apidoco_dsl
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/apidoco_dsl.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/apidoco_dsl.gemspec

@@ -0,0 +1,33 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "apidoco_dsl/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "apidoco_dsl"
+  spec.version       = ApidocoDsl::VERSION
+  spec.authors       = ["Steve Lewis"]
+  spec.email         = ["steve.l@lojistic.com"]
+
+  spec.summary       = %q{ Provides a block-based DSL for apidoco similar to ApiPie }
+  spec.homepage      = "https://github.com/lojistic/apidoco_dsl"
+  spec.license       = "MIT"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.add_dependency "apidoco", "~> 1.5"
+  spec.add_dependency "kramdown"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "apidoco_dsl"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/apidoco_dsl.rb

@@ -0,0 +1,42 @@
+require "apidoco_dsl/version"
+require "apidoco_dsl/documentable"
+require 'apidoco_dsl/param'
+require "apidoco_dsl/api"
+require 'apidoco_dsl/api_doc'
+require 'apidoco_dsl/param_group'
+require 'apidoco_dsl/railtie'
+
+module ApidocoDsl
+  class Error < StandardError; end
+
+  @@api = Api.new
+
+  def self.fetch_docs
+    return @@api.api_docs
+  end
+
+  def namespace(namespace)
+    @@api.namespace = namespace
+
+  end
+
+  def resource(resource)
+    @@api.resource = resource
+  end
+
+  def api_doc(&block)
+    api_doc = ApiDoc.new(@@api)
+    api_doc.instance_exec(&block)
+
+    @@api.api_docs << api_doc
+  end
+
+  def def_param_group(group_name, &block)
+    param_group = ParamGroup.new(group_name, @@api)
+    param_group.instance_exec(&block)
+
+    @@api.param_groups[group_name] = param_group
+  end
+
+
+end

data/lib/apidoco_dsl/api.rb

@@ -0,0 +1,10 @@
+module ApidocoDsl
+  class Api
+    attr_accessor :api_docs, :param_groups, :namespace, :resource
+
+    def initialize
+      @api_docs = []
+      @param_groups = {}
+    end
+  end
+end

data/lib/apidoco_dsl/api_doc.rb

@@ -0,0 +1,180 @@
+require 'kramdown'
+
+module ApidocoDsl
+  class ApiDoc
+    include Documentable
+    attr_accessor :doc_request_params, :doc_response_params, :doc_published, :doc_name,
+                  :doc_endpoint, :doc_http_method, :doc_header, :doc_examples,
+                  :doc_sort_order, :doc_description, :doc_request_example, :doc_response_example,
+                  :doc_return_code, :doc_namespace, :doc_resource, :doc_markdown
+
+    #attr_reader :api
+
+    SETTABLE = ['published', 'name', 'endpoint',
+                'http_method', 'header', 'markdown', 'sort_order']
+
+    def initialize(api)
+      @api                 = api
+      @doc_request_params  = []
+      @doc_response_params = []
+      @doc_examples        = []
+      @doc_namespace       = @api.namespace
+      @doc_resource        = @api.resource
+      @param_destination   = 'request'
+    end
+
+    def param_key
+      "Document"
+    end
+
+    def returns(code: 200, &block)
+      @doc_return_code = translate_return_code(code)
+      @param_destination = 'response'
+      self.instance_exec(&block) if block_given?
+      @param_destination = 'request'
+    end
+
+    def method_missing(name, *args)
+      return set_attribute(name, *args) if SETTABLE.include?(name.to_s)
+      super
+    end
+
+    def set_attribute(name, value)
+      self.send(:"doc_#{name}=", value)
+    end
+
+    def example_request(path: nil)
+      ex = {}
+      ex['request'] = yield if block_given?
+      ex['request'] = JSON.parse(File.read(path)) if path
+      @doc_examples << ex
+    end
+
+    def example_response(path: nil)
+      ex = {}
+      ex['response'] = yield if block_given?
+      ex['response'] = JSON.parse(File.read(path)) if path
+      @doc_examples << ex
+    end
+
+    def description(txt = nil, path: nil)
+      if path
+        txt  = File.read(path)
+        erb  = ERB.new(txt).result
+        html = Kramdown::Document.new(erb).to_html
+        @doc_description = ERB.new(html).result
+      else
+        @doc_description = txt
+      end
+    end
+
+    def doc_folder
+      doc_namespace.split('::').map(&:underscore).map(&:downcase).join('/') + "/#{doc_resource.to_s.underscore}/"
+    end
+
+    def doc_file
+      doc_name.gsub(/\s/, '').underscore
+    end
+
+    def to_json
+      doc = {}
+      doc['published']       = doc_published unless doc_published.nil?
+      doc['name']            = doc_name unless doc_name.nil?
+      doc['end_point']       = doc_endpoint unless doc_endpoint.nil?
+      doc['http_method']     = doc_http_method unless doc_http_method.nil?
+      doc['params']          = unroll_parameters(doc_request_params, [])  unless doc_request_params.empty?
+      doc['response_params'] = unroll_parameters(doc_response_params, []) unless doc_response_params.empty?
+      doc['header']          = doc_header unless doc_header.nil?
+      doc['description']     = doc_description unless doc_description.nil?
+      doc['examples']        = doc_examples unless doc_examples.empty?
+      doc['sort_order']      = doc_sort_order unless doc_sort_order.nil?
+      doc['return_code']     = doc_return_code
+      doc['markdown']        = doc_markdown
+
+      return JSON.pretty_generate(doc)
+    end
+
+    private
+
+    def translate_return_code(code)
+      trans = {
+        100 => :continue,
+        101 => :switching_protocols,
+        102 => :processing,
+        200 => :ok,
+        201 => :created,
+        202 => :accepted,
+        203 => :non_authoritative_information,
+        204 => :no_content,
+        205 => :reset_content,
+        206 => :partial_content,
+        207 => :multi_status,
+        226 => :im_used,
+        300 => :multiple_choices,
+        301 => :moved_permanently,
+        302 => :found,
+        303 => :see_other,
+        304 => :not_modified,
+        305 => :use_proxy,
+        307 => :temporary_redirect,
+        400 => :bad_request,
+        401 => :unauthorized,
+        402 => :payment_required,
+        403 => :forbidden,
+        404 => :not_found,
+        405 => :method_not_allowed,
+        406 => :not_acceptable,
+        407 => :proxy_authentication_required,
+        408 => :request_timeout,
+        409 => :conflict,
+        410 => :gone,
+        411 => :length_required,
+        412 => :precondition_failed,
+        413 => :request_entity_too_large,
+        414 => :request_uri_too_long,
+        415 => :unsupported_media_type,
+        416 => :requested_range_not_satisfiable,
+        417 => :expectation_failed,
+        422 => :unprocessable_entity,
+        423 => :locked,
+        424 => :failed_dependency,
+        426 => :upgrade_required,
+        500 => :internal_server_error,
+        501 => :not_implemented,
+        502 => :bad_gateway,
+        503 => :service_unavailable,
+        504 => :gateway_timeout,
+        505 => :http_version_not_supported,
+        507 => :insufficient_storage,
+        510 => :not_extended
+      }.invert
+
+      trans[code] || code
+    end
+
+    def unroll_parameters(params, unrolled = [])
+      # Unrolling parameters is a matter of recursively seeking down through each base set of params for
+      # each of _their_ params, and assigning/setting keys appropriately.
+
+      params.each do |pr|
+        if pr.params.any?
+
+          unrolled << pr.to_h
+          duped = pr.params.dup
+          duped.each{|d| d.parent = pr; }
+          unroll_parameters(duped, unrolled)
+        else
+          unrolled << pr.to_h
+        end
+
+      end
+
+      return unrolled
+    end
+
+    def push_to
+      self.send(:"doc_#{@param_destination}_params")
+    end
+
+  end
+end

data/lib/apidoco_dsl/documentable.rb

@@ -0,0 +1,65 @@
+module ApidocoDsl
+  module Documentable
+    attr_accessor :api
+
+    def param(key, type:, desc: nil, notes: nil, validations: nil, required: false, &block)
+      this_param = Param.new(
+        param_key: key,
+        param_type: type,
+        param_description: desc,
+        param_notes: notes,
+        param_required: required,
+        param_validations: validations,
+        parent: self
+      )
+
+      if block_given?
+        this_param.instance_exec(this_param, &block)
+      end
+
+      push_to << this_param
+    end
+
+    # There may be a clever way to do this, preserving key ancestry without duplication...I haven't found it.
+    def property(key, type:, desc: nil, notes: nil, validations: nil, required: true, &block)
+      this_param = Param.new(
+        param_key: key,
+        param_type: type,
+        param_description: desc,
+        param_notes: notes,
+        param_required: required,
+        param_validations: validations,
+        parent: self
+      )
+
+      if block_given?
+        this_param.instance_exec(this_param, &block)
+      end
+
+      push_to << this_param
+    end
+
+    def param_group(group_name)
+      # Param groups seem to have trouble inheriting parentage correctly.
+      # This appears to be because the params are "parented" when they are
+      # initally defined and when grabbing them here, we need to "re-parent"
+      # them...or more accurately, a copy of them.
+      #
+      # Again, problem, because a single param may itself have multiple layers
+      # of child params and groups...
+      #
+      # An interesting note here is that defining a nested grouping _manually_
+      # appears to have the desired effect.
+
+      pg = @api.param_groups[group_name].deep_dup
+      #pg.reparent(self) # Make the calling object the top-level parent for every param in this group
+
+      pg.params.each do |param|
+        push_to << param
+      end
+
+    end
+
+  end
+end
+

data/lib/apidoco_dsl/param.rb

@@ -0,0 +1,85 @@
+module ApidocoDsl
+  class Param
+    include Documentable
+
+      attr_accessor :param_key, :param_type, :param_description,
+                  :param_notes, :param_validations, :param_required, :params, :parent
+
+    SETTABLE = ['key', 'type', 'description', 'notes', 'validations', 'required']
+
+    def initialize(param_key:,
+                   param_type:,
+                   param_description: nil,
+                   param_notes: nil,
+                   param_validations: nil,
+                   param_required: false,
+                   parent: nil)
+
+      @param_key         = param_key
+      @param_type        = param_type
+      @param_description = param_description
+      @param_notes       = param_notes
+      @param_validations = param_validations
+      @param_required    = param_required
+      @parent            = parent
+      @params            = []
+      @api               = parent.api
+    end
+
+    def method_missing(name, *args)
+      return set_attribute(name, *args) if SETTABLE.include?(name.to_s)
+      super
+    end
+
+    def set_attribute(name, value)
+      self.send(:"param_#{name}=", value)
+    end
+
+    def doc_request_params
+      @params
+    end
+    alias doc_response_params doc_request_params
+
+    def to_h
+      param = {}
+      param['key'] =  compound_key
+      param['type'] = param_type unless param_type.nil?
+      param['description'] = param_description unless param_description.nil?
+      param['notes'] = param_notes unless param_notes.nil?
+      param['required'] = param_required
+      param['validations'] = param_validations unless param_validations.nil?
+
+      return param
+    end
+
+    def display_key
+      return param_key.to_s unless @parent && @parent.is_a?(Param)
+      return "[#{param_key.to_s}]"
+    end
+
+    private
+
+    def compound_key
+      return param_key.to_s unless @parent && @parent.is_a?(Param)
+
+      ancestors = []
+      this_parent = @parent
+      ancestor    = this_parent
+
+      while ancestor
+        ancestors << ancestor
+        ancestor = ancestor.try(:parent)
+      end
+
+      keys = ancestors.map{|a| a.try(:display_key) }.reverse
+
+      compounded = keys.map(&:to_s).join('')
+      return compounded + display_key
+    end
+
+    def push_to
+      @params
+    end
+
+  end
+end

data/lib/apidoco_dsl/param_group.rb

@@ -0,0 +1,53 @@
+module ApidocoDsl
+  class ParamGroup
+    include Documentable
+
+    attr_accessor :name, :params
+
+    def initialize(group_name, api)
+      @name   = group_name
+      @api    = api
+      @params = []
+      @doc_request_params = @params
+    end
+
+    def doc_request_params
+      @params
+    end
+    alias doc_response_params doc_request_params
+
+
+    def reparent(new_parent)
+      original_params = @params.deep_dup
+      @params = []
+
+      p '&&&&&&&&&&'
+      p '&&&&&&&&&&'
+      p '&&&&&&&&&&'
+      #original_params.each do |param|
+        #p param.parent.class
+        #p param.display_key #unless param.parent
+      #end
+
+      #original_params.each do |param|
+        #param = param.dup
+        #param.parent = new_parent
+
+        #@params << param
+      #end
+
+      @params.each do |param|
+        p param.parent.parent.class
+        p param.parent.display_key
+        p param.display_key #unless param.parent
+      end
+    end
+
+    private
+
+    def push_to
+      @params
+    end
+
+  end
+end

data/lib/apidoco_dsl/railtie.rb

@@ -0,0 +1,14 @@
+require 'apidoco_dsl'
+require 'rails'
+
+module ApidocoDsl
+  class Railtie < Rails::Railtie
+    railtie_name :apidoco_dsl
+
+    rake_tasks do
+      path = File.expand_path(__dir__ + '/../')
+      Dir.glob("#{path}/tasks/**/*.rake").each{|t| load t }
+    end
+  end
+end
+

data/lib/apidoco_dsl/version.rb

@@ -0,0 +1,3 @@
+module ApidocoDsl
+  VERSION = "0.1.0"
+end

data/lib/generators/apidoco_dsl/documentation_generator.rb

@@ -0,0 +1,18 @@
+module ApidocoDsl
+  module Generators
+    class DocumentationGenerator < Rails::Generators::Base
+      desc "Generate static JSON documentation for your API endpoints"
+
+      def generate_docs
+        docs = ApidocoDsl.fetch_docs
+        base_path = Apidoco.base_path
+
+        docs.each do |doc|
+          doc_path = "#{base_path}/#{doc.doc_folder}/#{doc.doc_file}.json"
+          create_file(doc_path, doc.to_json, force: true)
+        end
+      end
+    end
+  end
+end
+

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: apidoco_dsl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Steve Lewis
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-06-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: apidoco
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- steve.l@lojistic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- apidoco_dsl.gemspec
+- bin/console
+- bin/setup
+- lib/apidoco_dsl.rb
+- lib/apidoco_dsl/api.rb
+- lib/apidoco_dsl/api_doc.rb
+- lib/apidoco_dsl/documentable.rb
+- lib/apidoco_dsl/param.rb
+- lib/apidoco_dsl/param_group.rb
+- lib/apidoco_dsl/railtie.rb
+- lib/apidoco_dsl/version.rb
+- lib/generators/apidoco_dsl/documentation_generator.rb
+homepage: https://github.com/lojistic/apidoco_dsl
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lojistic/apidoco_dsl
+  source_code_uri: https://github.com/lojistic/apidoco_dsl
+  changelog_uri: https://github.com/lojistic/apidoco_dsl
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Provides a block-based DSL for apidoco similar to ApiPie
+test_files: []