grape-docs 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6480091004b71f2a3a6ddc2bf958f2f372d9fd24
+  data.tar.gz: 8817d24c6ae9b14813e4f91cf301917f4d76975d
+SHA512:
+  metadata.gz: 288642a1dc0c4163295cc6aea4feefc5cca8f69f4df890650aa1966cab83cd58a599aa0531ee0805e52b3114ccf53e234c86412d4f515bac03ab31389b5cf7ec
+  data.tar.gz: f1828a445b04cb792439f2e444778c2edbe1cd50d594ca3c529797fed751ba1304c80705afb3511b68de4393de4e8fbf2b1fc8671f67159299ad0223a1d3823a

data/README.md

@@ -0,0 +1,54 @@
+# grape-docs
+
+> Automatically generate markdown documentation from your grape API
+
+## Description
+
+grape-docs automagically generates documentation for your Grape API in various formats.
+
+The Gem will automatically analyze your Grape API structure, mounts, namespaces and routes, and will build a markdown documentation in separate files.
+
+It's best used combined with [GitBook](https://www.gitbook.com) and [gitbook-plugin-api](https://github.com/MagLoft/gitbook-plugin-api) to transform your markdown documentation into a good-looking and browsable API navigation.
+
+## Installation
+
+Install globally using `gem install grape-docs` or include it in your project Gemfile:
+
+```ruby
+source 'http://rubygems.org'
+
+gem 'grape-docs'
+```
+
+## Usage
+
+Run the `grape-docs export` command to export your documentation from within your Grape API project directory:
+
+```
+Usage:
+  grape-docs export <api_name> <export_path>
+
+Arguments:
+  <api_name>                 # Constant name of your Grape API, e.g. MyApp::Api
+  <export_path>              # Directory / path where the markdown documentation will be generated in
+
+Options:
+  -h, [--host=HOST]          # API Host
+                             # Default: https://api.example.com/
+  -t, [--template=TEMPLATE]  # Markdown template (default, gitbook) or custom (requires .md.erb extension)
+                             # Default: default
+  -r, [--require=REQUIRE]    # Ruby environment require path
+                             # Default: config/environment.rb
+
+Export documentation of API named <api_name> to <export_path> directory
+```
+
+## Result
+
+| Template `default`                                                       | Template `gitbook`                                                       |
+| :----------------------------------------------------------------------: | :----------------------------------------------------------------------: |
+| ![default](http://cdn.magloft.com/marketing/gems/grape-docs/default.png) | ![gitbook](http://cdn.magloft.com/marketing/gems/grape-docs/gitbook.png) |
+
+## License
+
+grape-docs is available under an MIT-style license.

data/bin/grape-docs

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require 'grape_docs/command'
+GrapeDocs::Command.start

data/lib/grape_docs.rb

@@ -0,0 +1,13 @@
+require "erb"
+require "json"
+require "workspace"
+require "active_support/inflector"
+require "grape_docs/api"
+require "grape_docs/endpoint"
+
+module GrapeDocs
+  @@config = { api_host: "https://api.example.com", template: "default" }
+  def self.config
+    @@config
+  end
+end

data/lib/grape_docs/api.rb

@@ -0,0 +1,22 @@
+module GrapeDocs
+  class Api
+    attr_reader :title, :detail, :path, :url, :endpoints, :children
+
+    def initialize(grape)
+      desc = grape.inheritable_setting.namespace[:description]
+      @title = desc ? desc[:description] : grape.name.titlecase
+      @detail = desc ? desc[:detail] : nil
+      @path = File.join(grape.inheritable_setting.namespace_stackable[:mount_path])
+      @url = File.join(GrapeDocs.config[:api_host], @path)
+      @endpoints = []
+      @children = []
+      grape.endpoints.each do |endpoint|
+        if endpoint.options.key?(:app)
+          @children.push(Api.new(endpoint.options[:app]))
+        elsif endpoint.routes.count > 0
+          @endpoints.push(Endpoint.new(self, endpoint))
+        end
+      end
+    end
+  end
+end

data/lib/grape_docs/command.rb

@@ -0,0 +1,45 @@
+require 'pry'
+require 'thor'
+require 'grape_docs'
+require 'grape_docs/version'
+require 'grape_docs/exporter'
+
+module GrapeDocs
+  class Command < Thor
+    map %w[--version -v] => :__print_version
+    desc "--version, -v", "print version number"
+    def __print_version
+      puts GrapeDocs::VERSION
+    end
+    desc "export <api_name> <export_path>", "Export documentation of API named <api_name> to <export_path> directory"
+    method_option :host, aliases: "-h", desc: "API Host", type: :string, default: "https://api.example.com/"
+    method_option :template, aliases: "-t", desc: "Markdown template (default, gitbook) or custom (requires .md.erb extension)", type: :string, default: "default"
+    method_option :require, aliases: "-r", desc: "Ruby environment require path", type: :string, default: "config/environment.rb"
+    def export(api_name, export_path)
+      # grape docs configuration
+      GrapeDocs.config[:api_host] = options.host
+      GrapeDocs.config[:template] = options.template
+
+      # prepare grape API
+      require_file = Workspace.file(options.require)
+      raise(Thor::Error, "ERROR: config/environment.rb doesn't exists!") unless require_file.exists?
+      require require_file.to_s
+      raise(Thor::Error, "ERROR: class #{api_name} isn't defined!") unless defined?(api_name)
+      api = Api.new(api_name.constantize)
+
+      # export grape API
+      exporter = Exporter.new(export_path)
+      exporter.export(api)
+    end
+
+    def self.banner(command, namespace = nil, subcommand = false)
+      result = "#{basename} #{command.usage}"
+      if namespace != false and command.name == "export"
+        result += "\n\nArguments:\n"
+        result += "  <api_name>                 # Constant name of your Grape API, e.g. MyApp::Api\n"
+        result += "  <export_path>              # Directory / path where the markdown documentation will be generated in\n"
+      end
+      result
+    end
+  end
+end

data/lib/grape_docs/endpoint.rb

@@ -0,0 +1,30 @@
+module GrapeDocs
+  class Endpoint
+    attr_reader :title, :detail, :path, :url, :params, :method, :model, :response
+
+    def initialize(api, endpoint)
+      options = endpoint.options[:route_options]
+      @title = options[:description] || endpoint.options[:path].first
+      @detail = options[:detail]
+      parent_path = File.join(endpoint.inheritable_setting.namespace_stackable[:mount_path])
+      @path = File.join(parent_path, endpoint.options[:path].first.to_s)
+      @url = File.join(GrapeDocs.config[:api_host], @path)
+      @params = options[:params].map { |p| p[1].merge(name: p[0]) }
+      @method = endpoint.options[:method].first
+      if options[:entity]
+        @model = options[:entity].documentation.map { |p| p[1].merge(name: p[0]) }
+        @response = build_response(@model)
+      end
+    end
+
+    private
+
+    def build_response(fields)
+      result = {}
+      fields.each do |field|
+        result[field[:name]] = field[:example]
+      end
+      result
+    end
+  end
+end

data/lib/grape_docs/exporter.rb

@@ -0,0 +1,62 @@
+module GrapeDocs
+  class Exporter
+    attr_reader :root, :template, :api
+
+    def initialize(export_path)
+      @root = Workspace.dir(File.expand_path(export_path)).clean
+
+      # load template
+      filename = "#{GrapeDocs.config[:template]}.md.erb"
+      current_dir = Workspace.dir(Dir.pwd)
+      template_file = current_dir.file(filename)
+      unless template_file.exists?
+        spec = Gem::Specification.find_by_name("grape-docs")
+        assets_dir = Workspace::Dir.new(spec.gem_dir).dir("assets")
+        template_file = assets_dir.file(filename)
+        unless template_file.exists?
+          template_file = assets_dir.file("default.md.erb")
+        end
+      end
+      @template = ERB.new(template_file.read, nil, "%")
+    end
+
+    def export(api)
+      @api = api
+      result = template.result(binding).gsub(/\n\n\n/, "\n\n")
+      root.file("#{api.path}.md").write(result)
+      api.children.each do |child|
+        export(child)
+      end
+    end
+
+    def table(params, *fields, &block)
+      params.each do |param|
+        yield param if block_given?
+      end
+      rows = []
+      rows.push(fields.map { |f| f.to_s.titlecase })
+      params.each do |param|
+        rows.push(fields.map { |f| param[f]&.to_s || "-" })
+      end
+      seperator = []
+      fields.each_with_index do |field, index|
+        field_max = rows.map { |row| row[index] }.max_by(&:length).length
+        seperator.push(":#{'-' * (field_max - 1)}")
+        rows.each_with_index do |row, i|
+          rows[i][index] = rows[i][index] + " " * (field_max - rows[i][index].length)
+        end
+      end
+      rows.insert(1, seperator)
+      rows.map { |row| "| #{row.join(' | ')} |" }.join("\n")
+    end
+
+    def json(data)
+      "```json\n#{JSON.pretty_generate(data)}\n```\n"
+    end
+
+    def document_url(target)
+      path = target.path.sub(%r{^/}, '')
+      "#{path}.md"
+    end
+  end
+end

data/lib/grape_docs/version.rb

@@ -0,0 +1,3 @@
+module GrapeDocs
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: grape-docs
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Tobias Strebitzer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: workspace
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.49'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.49'
+description: grape-docs automagically generates documentation for your Grape API in
+  various formats.
+email:
+- tobias.strebitzer@magloft.com
+executables:
+- grape-docs
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/grape-docs
+- lib/grape_docs.rb
+- lib/grape_docs/api.rb
+- lib/grape_docs/command.rb
+- lib/grape_docs/endpoint.rb
+- lib/grape_docs/exporter.rb
+- lib/grape_docs/version.rb
+homepage: https://github.com/magloft/grape-docs
+licenses:
+- BSD-3-Clause
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.4'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: Automatically generate documentation from grape API
+test_files: []