rspec-api-docs 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 93a03551851fab62786002d514811191321bcab5
-  data.tar.gz: cbde2ff103792b94141f1bb96092485b78882817
+  metadata.gz: 60a330ec02c82ad9a129e508386c67e173c0cd81
+  data.tar.gz: fed6d9f849bf9e1cee2cb44f04abce403353a064
 SHA512:
-  metadata.gz: 2789ae22918606ca1d572f8025bd4930540dc097c8a2606c9b28867b12c8d17a2750e77926d381d0e44f5ddef3c7c6d0d652edd076eb4830ecef81b0924f8c0c
-  data.tar.gz: af7acf8f314521c861a9c321be0939a93e6e8eab25e22b61a2a6cc3d4890d4f5f28ed41ac16f642e74b21eb6fd2036c6a6f2b667d116bc8c491fc80e8a74b1c6
+  metadata.gz: bc1785537527f94c561951c4ab62c6a0d37da817c26be4f55f8acbdaba7fc9cf14b31046c088a509b170a3fc36bb7484aa5c8d8fb93b956f5e7dd451572387cc
+  data.tar.gz: a258eba2025273e8f43a710d2f813c61633b7284d3a47714ed98b415557d54bbd4c6e88c0a29df19cd06597ad835a91cd16d5cc19cd78f4e7a20aab7cb2e416a

data/.gitignore

@@ -1 +1,3 @@
 /Gemfile.lock
+/pkg
+/.yardoc

data/.rubocop.yml

@@ -0,0 +1,55 @@
+AllCops:
+  TargetRubyVersion: 2.2
+  DisplayCopNames: true
+  DisabledByDefault: true
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/AbcSize:
+  Enabled: true
+
+Style/DotPosition:
+  EnforcedStyle: leading
+
+Style/AlignHash:
+  Enabled: true
+
+Style/ExtraSpacing:
+  AllowForAlignment: false
+
+Style/HashSyntax:
+  EnforcedStyle: ruby19
+
+Style/PercentLiteralDelimiters:
+  PreferredDelimiters:
+    '%':  '{}'
+    '%i': '[]'
+    '%q': '{}'
+    '%Q': '{}'
+    '%r': '{}'
+    '%s': '[]'
+    '%w': '[]'
+    '%W': '[]'
+    '%x': '[]'
+
+Style/SpaceInsideHashLiteralBraces:
+  EnforcedStyle: no_space
+
+Style/SpaceInsideBlockBraces:
+  EnforcedStyleForEmptyBraces: space
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/TrailingCommaInLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: nested
+
+Style/MultilineOperationIndentation:
+  EnforcedStyle: indented

data/README.md

@@ -1,4 +1,12 @@
-# rspec-api-docs
+<h1 align="center">rspec-api-docs</h1>
+
+<p align="center">Generate API documentation using RSpec</p>
+
+<p align="center">
+  <a href="https://travis-ci.org/twe4ked/rspec-api-docs"><img src="https://img.shields.io/travis/twe4ked/rspec-api-docs.svg?style=flat-square" /></a>
+  <a href="https://rubygems.org/gems/rspec-api-docs"><img src="https://img.shields.io/gem/v/rspec-api-docs.svg?style=flat-square" /></a>
+  <a href="http://www.rubydoc.info/github/twe4ked/rspec-api-docs/master"><img src="https://img.shields.io/badge/docs-master-lightgrey.svg?style=flat-square" /></a>
+</p>
 
 ## Installation
 
@@ -18,13 +26,213 @@ Or install it yourself as:
 
 ## Usage
 
-For now see the integration specs.
+**rspec-api-docs** works in two stages. The first stage introduces a new DSL
+method, `doc`, to include in your RSpec specs.
+
+``` ruby
+require 'rspec_api_docs/dsl'
+
+RSpec.describe 'Characters' do
+  include RspecApiDocs::Dsl
+
+  # ...
+end
+```
+
+The `doc` method stores data in a hash on the RSpec example metadata.
+
+The second stage is the formatter (`RspecApiDocs::Formatter`). The formatter
+parses the hash stored on each RSpec example and uses a renderer
+(lib/rspec_api_docs/formatter/renderer/) to write out your documentation.
+
+```
+bundle exec rspec spec/requests/characters_spec.rb --formatter=RspecApiDocs::Formatter
+```
+
+### DSL
+
+First, require the DSL and include the DSL module.
+
+You can do this in your `spec_helper.rb`:
+
+``` ruby
+require 'rspec_api_docs/dsl'
+
+RSpec.configure do |config|
+  config.include RspecApiDocs::Dsl, type: :request
+
+  # ...
+end
+```
+
+Or in individual specs:
+
+
+``` ruby
+require 'rspec_api_docs/dsl'
+
+RSpec.describe 'Characters' do
+  include RspecApiDocs::Dsl
+
+  # ...
+end
+```
+
+You also need to require a lambda that runs after each expectation:
+
+``` ruby
+require 'rspec_api_docs/after'
+
+RSpec.configure do |config|
+  config.after &RspecApiDocs::After::Hook
+end
+```
+
+This automatically stores the `last_request` and `last_response` objects for
+use by the formatter.
+
+**rspec-api-docs** doesn't touch any of the built-in RSpec DSL methods.
+Everything is contained in the `doc` block.
+
+You can use RSpec `before` blocks to share setup between multiple examples.
+
+``` ruby
+require 'rspec_api_docs/dsl'
+
+RSpec.describe 'Characters' do
+  include RspecApiDocs::Dsl
+
+  before do
+    doc do
+      resource_name 'Characters'
+      resource_description <<-EOF
+        Characters inhabit the Land of Ooo.
+      EOF
+    end
+  end
+
+  describe 'GET /characters/:id' do
+    it 'returns a character' do
+      doc do
+        name 'Fetching a Character'
+        description 'For getting information about a Character.'
+        path '/characters/:id'
+
+        field :id, 'The id of a character', scope: :character, type: 'integer'
+        field :name, "The character's name", scope: :character, type: 'string'
+      end
+
+      get '/characters/1'
+
+      # normal expectations ...
+    end
+
+    # ...
+  end
+end
+```
+
+#### `resource_name`
+
+Accepts a string of the name of the resource.
 
+> Characters
+
+#### `resource_description`
+
+Accepts a string that describes the resource.
+
+> Characters inhabit the Land of Ooo.
+
+#### `name`
+
+Accepts a string of the name of the resource.
+
+> Fetching a character
+
+Note: This defaults to the "description" of the RSpec example.
+
+
+``` ruby
+it 'Fetching a character' do
+  # ...
+end
+```
+
+#### `description`
+
+Accepts a string that describes the example.
+
+> To find out information about a Character.
+
+#### `path`
+
+Accepts a string for the path requested in the example.
+
+> /characters/:id
+
+Note: This defaults to the path of the first route requested in the example.
+
+#### `field`
+
+Accepts a `name`, `description`, and optionally a `scope` and `type`.
+
+- `name` [`Symbol`] the name of the response field
+- `description` [`String`] a description of the response field
+- `scope` [`Symbol`, `Array<Symbol>`] _(optional)_ how the field is scoped
+- `type` [`String`] _(optional)_ the type of the returned field
+
+This can be called multiple times for each response field.
+
+``` ruby
+field :id, 'The id of a character', scope: :character, type: 'integer'
+field :name, "The character's name", scope: :character, type: 'string'
 ```
-rm -rf spec/integration/output
-rspec spec/integration/rspec_api_docs_spec.rb --format=RspecApiDocs::Formatter
+
+#### `param`
+
+Accepts a `name`, `description`, and optionally a `scope`, `type`, and `required` flag.
+
+- `name` [`Symbol`] the name of the parameter
+- `description` [`Symbol`] a description of the parameter
+- `scope` [`Symbol`, `Array<Symbol>`] _(optional)_ how the parameter is scoped
+- `type` [`String`] _(optional)_ the type of the parameter
+- `required` [`Boolean`] _(optional)_ if the parameter is required
+
+This can be called multiple times for each parameter.
+
+``` ruby
+param :id, 'The id of a character', scope: :character, type: 'integer', required: true
+param :name, "The character's name", scope: :character, type: 'string'
 ```
 
+See the integration specs for more examples of the DSL in use.
+
+### Formatter
+
+The formatter can be configured in your `spec_helper.rb`:
+
+``` ruby
+# Defaults are shown
+
+RspecApiDocs.configure do |config|
+  # The output directory for file(s) created by the renderer.
+  config.output_dir = 'docs'
+
+  # One of :json, :raddocs, or :slate.
+  # This can also be a class that quacks like a renderer.
+  # A renderer is initialized with an array of `Resource`s and a `#render`
+  # method is called.
+  config.renderer = :json
+
+  # Set to false if you don't want to validate params are documented and their
+  # types in the after block.
+  config.validate_params = true
+end
+```
+
+See [the documentation](http://www.rubydoc.info/github/twe4ked/rspec-api-docs/master).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
@@ -35,6 +243,16 @@ 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].
 
+Regenerate this project's integration spec docs locally:
+
+```
+./bin/generate_integration_docs
+```
+
+## TODO
+
+- Allow specifying an order (`precedence`?)
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at

data/Rakefile

@@ -1,6 +1,13 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new :rspec do |task|
+  task.verbose = false
+end
 
-task default: :spec
+RuboCop::RakeTask.new :rubocop do |task|
+  task.verbose = false
+end
+
+task default: [:rspec, :rubocop]

data/bin/generate_integration_docs

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash -ex
+
+rm -rf spec/integration/output
+
+bundle exec rspec spec/integration/*_spec.rb --format RspecApiDocs::Formatter --require ./spec/integration/json_helper.rb
+bundle exec rspec spec/integration/*_spec.rb --format RspecApiDocs::Formatter --require ./spec/integration/raddocs_helper.rb
+bundle exec rspec spec/integration/*_spec.rb --format RspecApiDocs::Formatter --require ./spec/integration/slate_helper.rb
+
+{ set +x; } 2>/dev/null
+
+if [[ -n "$(git status -z --porcelain spec/integration/output)" ]]; then
+  git diff spec/integration/output
+  exit 1
+fi

data/lib/rspec_api_docs.rb

@@ -1,22 +1,8 @@
+require 'rspec_api_docs/config'
 require 'rspec_api_docs/version'
 
 module RspecApiDocs
   METADATA_NAMESPACE = :rspec_api_docs
 
-  class << self
-    attr_accessor :configuration
-  end
-
-  def self.configure
-    self.configuration ||= Config.new
-    yield configuration
-  end
-
-  class Config
-    attr_accessor :output_dir
-
-    def initialize
-      @output_dir = 'docs'
-    end
-  end
+  BaseError = Class.new(StandardError)
 end

data/lib/rspec_api_docs/after.rb

@@ -1,10 +1,27 @@
+require 'rspec_api_docs/after/type_checker'
+
 module RspecApiDocs
-  After = -> (example) do
-    metadata = example.metadata[METADATA_NAMESPACE]
+  UndocumentedParameter = Class.new(BaseError)
+
+  class After
+    Hook = -> (example) do
+      metadata = example.metadata[METADATA_NAMESPACE]
+      return unless metadata
 
-    if metadata
       metadata[:requests] ||= []
       metadata[:requests] << [last_request, last_response]
+
+      return unless RspecApiDocs.configuration.validate_params
+
+      metadata[:requests].each do |request, response|
+        request.params.each do |key, value|
+          if metadata[:parameters] && metadata[:parameters].has_key?(key.to_sym)
+            After::TypeChecker.call(type: metadata[:parameters][key.to_sym][:type], value: value)
+          else
+            raise UndocumentedParameter, "undocumented parameter included in request #{key.inspect}"
+          end
+        end
+      end
     end
   end
 end

data/lib/rspec_api_docs/after/type_checker.rb

@@ -0,0 +1,56 @@
+module RspecApiDocs
+  class After
+    class TypeChecker
+      UnknownType = Class.new(BaseError)
+      TypeError = Class.new(BaseError)
+
+      attr_reader :type, :value
+
+      def self.call(*args)
+        new(*args).check
+      end
+
+      def initialize(type:, value:)
+        @type = type
+        @value = value
+      end
+
+      def check
+        case type
+        when /integer/i
+          is_integer?(value) or raise_type_error
+        when /float/i
+          is_float?(value) or raise_type_error
+        when /boolean/i
+          is_bool?(value) or raise_type_error
+        when /string/i
+          # NO OP
+        else
+          raise UnknownType, "unknown type #{type.inspect}"
+        end
+      end
+
+      private
+
+      def is_integer?(str)
+        Integer(str) && true
+      rescue ArgumentError
+        false
+      end
+
+      def is_float?(str)
+        Float(str) && true
+      rescue ArgumentError
+        false
+      end
+
+      def is_bool?(str)
+        %w[true false].include?(str)
+      end
+
+      def raise_type_error
+        raise TypeError, "wrong type #{value.inspect}, expected #{type.inspect}"
+      end
+    end
+  end
+end