dox 1.0.0.alpha → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9535d1b95849fc4c0dddff91c5ed6a35879d6505
-  data.tar.gz: c84f5af01e5de1524b533175a6141d67b995bee3
+  metadata.gz: e3696fee9fddea2f824f129a0a25e61383b01cec
+  data.tar.gz: c69809b3ce6618fc593dd8897938e5f34d8788c9
 SHA512:
-  metadata.gz: a7ee68d768d9fbbf34708e1cbb901fee9dd532d09807cbd9ffa0abb60d08d80c08114014280390f8532788b68e517d29dc70ebdb6ab678057e0dbfc51566ad3d
-  data.tar.gz: 900ec7205240057d71ae6f8c1753aabe9d03d66375dbf167336b7444f2d5840969b1ed510cf25011963807c382c051976a7fb6189178ebe1335ed96370fab653
+  metadata.gz: 28f6f85ab7471792a741658f83a1a1b522359da8bed3e4bd5f9e9a4cf71d9e28e80fe1a087fc459bd9c4c58afbde4cb797ceb0732d7a3980556c2c973bf7838e
+  data.tar.gz: 2e71c5e388fc0c7bb727f057219e6376b4a2fe80a645738fef539ced75d1099227a27c8ac786b2c8c160c98e99fc99b22a2e0404dc414d7b3a0f2276b1e9bd7a

data/.gitignore

@@ -7,3 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+
+*.gem

data/.rubocop.yml

@@ -0,0 +1,14 @@
+LineLength:
+  Max: 120
+
+Documentation:
+  Enabled: False
+
+WordArray:
+  Enabled: False
+
+AllCops:
+  TargetRubyVersion: 2.3
+
+Style/FrozenStringLiteralComment:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/.travis.yml

@@ -1,4 +1,25 @@
 language: ruby
-rvm:
-  - 2.3.0
 before_install: gem install bundler -v 1.11.2
+
+matrix:
+  include:
+    - rvm: 2.0.0
+      env: "RAILS_VERSION=4.0.0"
+    - rvm: 2.1.2
+      env: "RAILS_VERSION=4.1.0"
+    - rvm: 2.2.0
+      env: "RAILS_VERSION=4.2.0"
+    - rvm: 2.2.2
+      env: "RAILS_VERSION=5.0.0"
+    - rvm: 2.3.0
+      env: "RAILS_VERSION=5.0.0"
+    - rvm: 2.4.0
+      env: "RAILS_VERSION=5.0.0"
+
+addons:
+  code_climate:
+    repo_token:
+      secure: "LsnC+ru4oLhNOo0YFUfQeVvnCLkfeOv7xN9xSaBO2J1K2qZCadjsX/gnV6BRU5wmAxyXR2xQGnI+9wi4dqlPcuXlTIbE4Ge91WoTU+DNjA8RBrYePfVGsNeuT5wos6I0nBmnNYujBS6Rk0ntc1WEV2nq+3K4dpiTNcAYtS1f8zwV7qXBU63hc3urL0tO6DQUIYOi1rlse2EO5vhBlm3dH24TqEz32RROxh0kkuNLPmoq9NHCZQuJl1I0D3ovW+NRcOYDcgALX4HMRk8+4Hoqz3gyalLNvFujBdwnObL6kiMdRuUO8SGIc2crVMdckAnDBOkYYO4GQUwPv4qzaSX15i8Hrdxz16Rh9saqmX7qacornatt85j0aXA7nDPTD2zxG749XPu1DsUz0VC/2vWbCFhk9VysVtiY/grcUXg1CC/uh0+xbrnZol4rlInXyuXxmWOKThzMeSPjR0aCkQwqpRWG9ck0VTQIcC2mPGIF4o6fsMYe6iDtwPixNsCHBTPa/Ack0rgnxCvb5SH59VK0p4bTgzY/st85mBht1t46sqkbhdDI0S/oJu0NgmpyBAB6RL/kjNlVHvSi4plQxhW2N0FyQpwnLGkvxidIRwqnd1YalJxja2RDe7LaB82zusX+GLl0T79tW4VGEm8PqC7i3COMsWji8P75eiVzvwISN8w="
+
+after_success:
+  - bundle exec codeclimate-test-reporter

data/CHANGES.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## Version 1.0.0
+
+Released on May 6, 2017
+
+New:
+- Guess path params for URI definition from example's request object
+- Validate HTTP verbs specified in the descriptors' actions
+- Document only examples whitelisted with `dox` tag
+- Added option for whitelisting additional HTTP headers for examples
+- Show request HTTP verb and fullpath for each action request
+- Dox executable
+
+Fix:
+- Ignore body in query params (Rails 4 issue) for example request URL
+- Pull request and response objects from example metadata
+
+## Version 1.0.0.alpha
+
+Released on October 18, 2016
+
+- Updated the dependencies
+
+New:
+- Raise errors on missing required dox attributes in descriptors
+- `extend Dox::DSL::Syntax` instead of `include Dox::DSL::Syntax` in descriptors
+
+
+## Version 0.0.3
+
+Released on June 22, 2016
+
+Fix:
+- Fixed example identifier for examples with query params
+
+
+## Version 0.0.2
+
+
+Released on June 14, 2016
+
+- Created core classes and a DSL for manipulating the examples in specs
+- Added usage to readme
+
+
+## Version 0.0.1
+
+Released on June 06, 2016
+
+- First release of the dox gem where the initial gem skeleton has been created

data/Gemfile

@@ -2,3 +2,7 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in dox.gemspec
 gemspec
+
+rails_version = ENV['RAILS_VERSION'] || '5.0.1'
+
+gem 'rails', "~> #{rails_version}"

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Melita Kokot
+Copyright (c) 2017 Infinum
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,114 +1,297 @@
+[![Build Status](https://travis-ci.org/infinum/dox.svg?branch=master)](https://travis-ci.org/infinum/dox)
+[![Code Climate](https://codeclimate.com/github/infinum/dox/badges/gpa.svg)](https://codeclimate.com/github/infinum/dox)
+[![Test Coverage](https://codeclimate.com/github/infinum/dox/badges/coverage.svg)](https://codeclimate.com/github/infinum/dox/coverage)
+
 # Dox
 
-Dox formats the rspec output in the [api blueprint](https://apiblueprint.org/) format.
+Automate your documentation writing proces! Dox generates API documentation from Rspec controller/request specs in a Rails application. It formats the tests output in the [API Blueprint](https://apiblueprint.org) format. Choose one of the [renderes](#renderers) to convert it to HTML or host it on [Apiary.io](https://apiary.io)
+
+Here's a [demo app](https://github.com/infinum/dox-demo) and here are some examples:
+
+- [Dox demo - Apiary](http://docs.doxdemo.apiary.io/#reference/books/books)
+- [Dox demo - Aglio](https://infinum.github.io/dox-demo/aglio)
+- [Dox demo - Snowboard](https://infinum.github.io/dox-demo/snowboard)
+
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'dox'
+group :test do
+  gem 'dox', require: 'false'
+end
 ```
 
 And then execute:
 
-    $ bundle
+```
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install dox
+```
+$ gem install dox
+```
 
 ## Usage
 
-### Code example
+### Require it
+ Require Dox in the rails_helper:
 
-Example documentation module for a resource:
+ ``` ruby
+ require 'dox'
+ ```
+
+and configure rspec with this:
 
 ``` ruby
-module ApiDoc
+Rspec.configure do |config|
+  config.after(:each, :dox) do |example|
+    example.metadata[:request] = request
+    example.metadata[:response] = response
+  end
+end
+```
+
+### Configure it
+Set these mandatory options in the rails_helper:
+
+| Option | Value | Description |
+| -- | -- | -- |
+| header_file_path | Pathname instance or fullpath string | Markdown file that will be included at the top of the documentation. It should contain title and some basic info about the api. |
+| desc_folder_path | Pathname instance or fullpath string | Folder with markdown descriptions. |
+
+
+Optional settings:
+
+| Option | Value| Description |
+| -- | -- | -- |
+| headers_whitelist | Array of headers (strings) | Requests and responses will by default list only `Content-Type` header. To list other http headers, you must whitelist them.|
+
+Example:
+
+``` ruby
+Dox.configure do |config|
+  config.header_file_path = Rails.root.join('spec/docs/v1/descriptions/header.md')
+  config.desc_folder_path = Rails.root.join('spec/docs/v1/descriptions')
+  config.headers_whitelist = ['Accept', 'X-Auth-Token']
+end
+```
+
+### Basic example
+
+Define a descriptor module for a resource using Dox DSL:
+
+``` ruby
+module Docs
   module V1
     module Bids
-      include Dox::DSL::Syntax
+      extend Dox::DSL::Syntax
 
+      # define common resource data for each action
       document :api do
-        group do
-          name 'Bids'
-        end
-
-        resource do
-          name 'Bids'
+        resource 'Bids' do
           endpoint '/bids'
           group 'Bids'
-          desc 'bid_resource.md'
         end
       end
 
+      # define data for specific action
       document :index do
-        action do
-          name 'Get bids'
-          verb 'GET'
-          path '/bids'
-          desc 'Returns list of user bids'
-        end
-      end
-
-      document :create do
-        action do
-          name 'Post bids'
-          verb 'POST'
-          path '/bids'
-          desc 'Creates bid'
-        end
+        action 'Get bids'
       end
     end
   end
 end
+
+```
+<small>You can define the descriptors for example in specs/docs folder, just make sure you load them in the rails_helper.rb:
+
+``` ruby
+Dir[Rails.root.join('spec/docs/**/*.rb')].each { |f| require f }
 ```
-Description can be included inline or relative path of a markdown file with the description (relative to configured folder for markdown descriptions).
+</small>
 
-Including the documentation module in a controller:
+Include the descriptor modules in a controller and tag the specs you want to document with **dox**:
 
 ``` ruby
 describe Api::V1::BidsController, type: :controller do
-  include ApiDoc::V1::Bids::Api
+  # include resource module
+  include Docs::V1::Bids::Api
 
   describe 'GET #index' do
-    include ApiDoc::V1::Bids::Index
+    # include action module
+    include Docs::V1::Bids::Index
 
-    it 'returns a list of bids' do
+    it 'returns a list of bids', :dox do
       get :index
       expect(response).to have_http_status(:ok)
     end
+  end
+end
+```
+
+And [generate the documentation](#generate-documentation).
+
+
+### Advanced options
+
+Before running into any more details, here's roughly how is the generated API Blueprint document structured:
 
+- header
+- resource group
+  - resource
+    - action
+      - example 1
+      - example 2
+    - action
+    - ...
+  - resource
+    - action
+  - ...
+- resource group
+  - resource
+    - action
+
+
+Header is defined in a markdown file as mentioned before. Examples are concrete test examples (you can have 2 examples for create 1 happy path, 1 fail path). They are completely automatically generated from the request/response objects.
+And you can customize the following in the descriptors:
+
+- resource group
+- resource
+- action
+
+#### Resource group
+
+Resource group contains related resources and is defined with:
+- **name** (required)
+- desc (optional, inline string or relative filepath)
+
+Example:
+``` ruby
+document :bids_group do
+  group 'Bids' do
+    desc 'Here are all bid related resources'
+  end
+end
+```
+
+You can omit defining the resource group, if you don't have any description for it. Related resources will be linked in a group by the group option at the resource definition.
+
+#### Resource
+Resource contains actions and is defined with:
+- **name** (required)
+- **endpoint** (required)
+- **group** (required; to associate it with the related group)
+- desc (optional; inline string or relative filepath)
+
+Example:
+``` ruby
+document :bids do
+  resource 'Bids' do
+    endpoint '/bids'
+    group 'Bids'
+    desc 'bids/bids.md'
   end
 end
 ```
 
-### Configuration
+Usually you'll want to define resource and resource group together, so you don't have to include 2 modules with common data per spec file:
 
-You have to specify **root api file** and **descriptions folder**.
+``` ruby
+document :bids_common do
+  group 'Bids' do
+    desc 'Here are all bid related resources'
+  end
 
-Root api file is a markdown file that will be included in the top of the documentation. It should contain title and some basic info about the api.
+  resource 'Bids' do
+    endpoint '/bids'
+    group 'Bids'
+    desc 'bids/bids.md'
+  end
+end
+```
+
+#### Action
+Action is defined with:
+- **name** (required)
+- path* (optional)
+- verb* (optional)
+- params* (optional)
+- desc (optional; inline string or relative filepath)
 
-Descriptions folder is a fullpath of a folder that contains markdown files with descriptions which behave like partials and are included in the final concatenated markdown. Root api file should also be in this folder.
+\* these optional attributes are guessed (if not defined) from the request object of the test example and you can override them.
+
+Example:
 
 ``` ruby
-Dox.configure do |config|
-  config.header_file_path = 'api.md'
-  config.desc_folder_path = Rails.root.join('spec/support/api_doc/v1/markdown_descriptions')
+show_params = { id: { type: :number, required: :required, value: 1, description: 'bid id' } }
+
+document :action do
+  action 'Get bid' do
+    path '/bids/{id}'
+    verb 'GET'
+    params show_params
+    desc 'Some description for get bid action'
+  end
 end
 ```
 
-### Generate HTML documentation
-You have to install [aglio](https://www.npmjs.com/package/aglio).
+### Generate documentation
+Documentation is generated in 2 steps:
+
+1. generate API Blueprint markdown with dox command:
+```bundle exec dox spec/controllers/api/v1 > docs.md```
+
+2. render HTML with some renderer, for example, with Aglio:
+```aglio -i docs.md -o docs.html```
+
+
+#### Renderers
+You can render the HTML yourself with one of the renderers:
+
+- [Aglio](https://github.com/danielgtaylor/aglio)
+- [Snowboard](https://github.com/subosito/snowboard)
+
+Both support multiple themes and template customization.
+
+Or you can just take your generated markdown and host your documentation on [Apiary.io](https://apiary.io).
+
+
+### Common issues
+
+You might experience some strange issues when generating the documentation. Here are a few examples of what we've encountered so far.
 
-Rake task for generating HTML:
+#### Wrap parameters issue
+Rails wraps JSON parameters on all requests by default, which results with documented requests looking like this:
+
+```
++ Request get pokemons
+    {
+      "pokemon": {}
+    }
+```
+
+To disable wrapping parameters with a resource name, turn off this feature in `config/initializers/wrap_parameters.rb`:
 
 ``` ruby
-  `bundle exec rspec spec --tag apidoc -f Dox::Formatter --order defined --out spec/apispec.md`
-  `aglio --include-path / -i spec/apispec.md -o public/api/docs/index.html`
+# Enable parameter wrapping for JSON. You can disable this by setting :format to an empty array.
+ActiveSupport.on_load(:action_controller) do
+  wrap_parameters format: []
+end
 ```
 
+#### Rendering warnings with Aglio
+You might get the following warnings when rendering HTML with Aglio:
+
+* `no headers specified (warning code 3)`
+* `empty request message-body (warning code 6)`
+
+This usually happens on GET requests examples when there are no headers. To solve this issue, add at least one header to the tests' requests, like `Accept: application/json`.
+
+
 ## 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.
@@ -117,8 +300,13 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/dox. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/infinum/dox. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## Credits
+Dox is maintained and sponsored by [Infinum](https://infinum.co).
 
+<a href="https://infinum.co"><img alt="Infinum" src="infinum.png" width="250"></a>
 
 ## License