dox 1.3.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: bb133ea037943a10f5732ebcb2418ff01eb3664d
-  data.tar.gz: be31d122d267c510391b7813a662e2a8eb212d9f
+SHA256:
+  metadata.gz: 90c15cf757218b0357b046e8d4170b96ce3fb0072c59f68141653e04c0dd9a2e
+  data.tar.gz: 47f6d55378aad845267e8d86ecb9a75f1625a0599ec35501bb0dd77f6006d97e
 SHA512:
-  metadata.gz: d1deea6577862b637989fc13e783434a5120cfa6fd4c1b6d004fc25bcdc045316b45386f060eea5be0f0273655f2cd56ba0acee22e50a183eaf54422083fb729
-  data.tar.gz: e52dce445ee7da4fbad81137af4b8c6eb3a77e1b3700b45a11290c80d87ca8dfe1fa519c313c2ced88c293eac23b0dc410a20535715015d0293bfbec53b3bf59
+  metadata.gz: dd57224cb90c0803256d6427fbd520324d5eef21b2f66edcb0f4881fec48943e39eecb08eb42a39808c13fa1f121e8af3f69f8668c130616e96ea5ca67f0a396
+  data.tar.gz: cd21d5496bfc0d28549be4546b0cf6f34bda12bcc05fc792dd2a0db7ac12a7a2199c18ddf20cef4c04d19b112dbb1b602f5dbe85843e6863f478737255bab89e

data/.rubocop.yml

@@ -7,8 +7,11 @@ Documentation:
 WordArray:
   Enabled: False
 
-AllCops:
-  TargetRubyVersion: 2.3
-
 Style/FrozenStringLiteralComment:
   Enabled: false
+
+BlockLength:
+  Max: 250
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false

data/.ruby-version

@@ -1 +1 @@
-2.3.1
+2.5.5

data/.travis.yml

@@ -1,20 +1,16 @@
 language: ruby
-before_install: gem install bundler -v 1.11.2
+# before_install: gem install bundler -v 1.17.3
 
 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"
+    - rvm: 2.5.0
+      env: "RAILS_VERSION=5.0.0"
+    - rvm: 2.6.0
+      env: "RAILS_VERSION=6.0.0"
+    - rvm: 2.7.0
+      env: "RAILS_VERSION=6.0.0"
 
 addons:
   code_climate:

data/CHANGES.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## Version 1.3.0
+## Version 2.1.0
 
 Released on March 26, 2021
 
@@ -10,6 +10,24 @@ Add:
 Drop:
 - 'rails' as a runtime dependency
 
+## Version 2.0.0
+
+Released on August 8, 2020
+
+Change:
+- BREAKING CHANGE The API description format changed from API-blueprint to OpenAPI.
+- BREAKING CHANGE Base structure is now defined in .json format
+- BREAKING CHANGE Output is written to a .json file
+- BREAKING CHANGE Html is rendered with Redoc instead of Aglio
+- Renamed `Dox.config.desc_folder_path` -> `Dox.config.descriptions_location`
+- Depricated `Dox.config.header_file_path`
+- Removed `endpoint` method from document resource block
+
+New:
+- Added `Dox.config.title`
+- Added `Dox.config.header_description`
+- Added `Dox.config.version`
+
 ## Version 1.2.0
 
 Released on November 27, 2019

data/Gemfile

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

data/README.md

@@ -4,13 +4,9 @@
 
 # Dox
 
-Automate your documentation writing process! Dox generates API documentation from Rspec controller/request specs in a Rails application. It formats the test's output in the [API Blueprint](https://apiblueprint.org) format. Choose one of the [renderers](#renderers) to convert it to HTML or host it on [Apiary.io](https://apiary.io)
+Automate your documentation writing process! Dox generates API documentation from Rspec controller/request specs in a Rails application. It formats the tests output in the [OpenApi](https://www.openapis.org/) format. Use the ReDoc renderer for generating and displaying the documentation as HTML.
 
-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)
+Here's a [demo app](https://github.com/infinum/dox-demo).
 
 
 ## Installation
@@ -44,39 +40,33 @@ $ gem install dox
  require 'dox'
  ```
 
-and configure rspec with this:
-
-``` ruby
-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:
+Set these optional 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 |
-| -- | -- | -- |
+| descriptions_location | Pathname instance or fullpath string | Folder containing markdown descriptions of resources. |
+| schema_request_folder_path | Pathname instance or fullpath string | Folder with request schemas of resources. |
+| schema_response_folder_path | Pathname instance or fullpath string | Folder with response schemas of resources. |
+| schema_response_fail_file_path | Pathname instance or fullpath string | Json file that contains the default schema of a failed response. |
+| openapi_version | string | Openapi version (default: '3.0.0' ) |
+| api_version | string | Api Version (default: '1.0') |
+| title | string | Documentation title (default: 'API Documentation') |
+| header_description | Pathname instance or string | Description (header) of the documentation (default: ''). If pathname ends with `.md`, the file is looked in `descriptions_location` folder |
 | 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.descriptions_location  = Rails.root.join('spec/docs/v1/descriptions')
+  config.schema_request_folder_path = Rails.root.join('spec/docs/v1/schemas')
+  config.schema_response_folder_path = Rails.root.join('spec/support/v1/schemas')
+  config.schema_response_fail_file_path = Rails.root.join('spec/support/v1/schemas/error.json')
   config.headers_whitelist = ['Accept', 'X-Auth-Token']
+  config.title = 'API'
+  config.api_version = '2.0'
+  config.header_description = 'api_description.md'
 end
 ```
 
@@ -93,8 +83,8 @@ module Docs
       # define common resource data for each action
       document :api do
         resource 'Bids' do
-          endpoint '/bids'
           group 'Bids'
+          desc 'bids.md'
         end
       end
 
@@ -138,34 +128,41 @@ 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.
+Before running into any more details, here's roughly how the generated OpenApi document is structured:
+
+- openapi
+- info
+- paths
+  - action 1
+    - tag1
+    - example 1
+    - example 2
+  - action 2
+    - tag2
+    - example 3
+- x-tagGroups
+      - tags1
+        - tag 1
+        - tag 2
+      - tags2
+        - tag 3
+        - tag 4
+- tags
+  - tag1
+  - tag2
+
+
+OpenApi and info are defined in a json file as mentioned before. Examples are concrete test examples (you can have multiple examples for both happy and fail paths). They are completely automatically generated from the request/response objects.
 And you can customize the following in the descriptors:
 
-- resource group
-- resource
+- x-tagGroup (**resourceGroup**)
+- tag (**resource**)
 - action
+- example
 
-#### Resource group
+#### ResourceGroup
 
-Resource group contains related resources and is defined with:
+ResourceGroup contains related resources and is defined with:
 - **name** (required)
 - desc (optional, inline string or relative filepath)
 
@@ -183,7 +180,6 @@ You can omit defining the resource group, if you don't have any description for
 #### 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)
 
@@ -191,14 +187,13 @@ Example:
 ``` ruby
 document :bids do
   resource 'Bids' do
-    endpoint '/bids'
     group 'Bids'
     desc 'bids/bids.md'
   end
 end
 ```
 
-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:
+Usually you'll want to define resourceGroup and resource together, so you don't have to include 2 modules with common data per spec file:
 
 ``` ruby
 document :bids_common do
@@ -207,7 +202,6 @@ document :bids_common do
   end
 
   resource 'Bids' do
-    endpoint '/bids'
     group 'Bids'
     desc 'bids/bids.md'
   end
@@ -215,12 +209,16 @@ end
 ```
 
 #### Action
-Action is defined with:
+Action contains examples and is defined with:
 - **name** (required)
 - path* (optional)
 - verb* (optional)
-- params* (optional)
+- params (optional; _depricated_)
+- query_params (optional; [more info](https://swagger.io/docs/specification/describing-parameters/#query-parameters))
 - desc (optional; inline string or relative filepath)
+- request_schema (optional; inline string or relative filepath)
+- response_schema_success (optional; inline string or relative filepath)
+- response_schema_fail (optional; inline string or relative filepath)
 
 \* these optional attributes are guessed (if not defined) from the request object of the test example and you can override them.
 
@@ -228,13 +226,37 @@ Example:
 
 ``` ruby
 show_params = { id: { type: :number, required: :required, value: 1, description: 'bid id' } }
+query_params = [ {
+  "in": "query",
+  "name": "filter",
+  "required": false,
+  "style": "deepObject",
+  "explode": true,
+  "schema": {
+    "type": "object",
+    "required": ["updated_at_gt"],
+    "example": {
+      "updated_at_gt": "2018-02-03 10:30:00"
+    },
+    "properties": {
+      "updated_at_gt": {
+        "type": "string",
+        "title": "date"
+      }
+    }
+  }
+]
 
 document :action do
   action 'Get bid' do
     path '/bids/{id}'
     verb 'GET'
     params show_params
+    query_params query_params
     desc 'Some description for get bid action'
+    request_schema 'namespace/bids'
+    response_schema_success 'namespace/bids_s'
+    response_schema_fail 'namespace/bids_f'
   end
 end
 ```
@@ -242,56 +264,53 @@ end
 ### Generate documentation
 Documentation is generated in 2 steps:
 
-1. generate API Blueprint markdown:
-```bundle exec rspec spec/controllers/api/v1 -f Dox::Formatter --order defined --tag dox --out docs.md```
+1. generate OpenApi json file:
+```bundle exec rspec --tag apidoc -f Dox::Formatter --order defined --tag dox --out spec/api_doc/v1/schemas/docs.json```
 
-2. render HTML with some renderer, for example, with Aglio:
-```aglio -i docs.md -o docs.html```
+2. render HTML with Redoc:
+```redoc-cli bundle -o public/api/docs/v2/docs.html spec/api_doc/v1/schemas/docs.json```
 
 
 #### Use rake tasks
 It's recommendable to write a few rake tasks to make things easier. Here's an example:
 
 ```ruby
-namespace :api do
-  namespace :doc do
-    desc 'Generate API documentation markdown'
-    task :md do
-      require 'rspec/core/rake_task'
-
-      RSpec::Core::RakeTask.new(:api_spec) do |t|
-        t.pattern = 'spec/controllers/api/v1/'
-        t.rspec_opts = "-f Dox::Formatter --order defined --tag dox --out public/api/docs/v1/apispec.md"
-      end
+namespace :dox do
+  desc 'Generate API documentation markdown'
 
-      Rake::Task['api_spec'].invoke
-    end
+  task :json, [:version, :docs_path, :host] => :environment do |_, args|
+    require 'rspec/core/rake_task'
+    version = args[:version] || :v1
 
-    task html: :md do
-      `aglio -i public/api/docs/v1/apispec.md -o public/api/docs/v1/index.html`
+    RSpec::Core::RakeTask.new(:api_spec) do |t|
+      t.pattern = "spec/requests/api/#{version}"
+      t.rspec_opts =
+        "-f Dox::Formatter --tag dox --order defined --out spec/docs/#{version}/apispec.json"
     end
 
-    task open: :html do
-      `open public/api/docs/v1/index.html`
-    end
+    Rake::Task['api_spec'].invoke
+  end
 
-    task publish: :md do
-      `apiary publish --path=public/api/docs/v1/apispec.md --api-name=doxdemo`
-    end
+  task :html, [:version, :docs_path, :host] => :json do |_, args|
+    version = args[:version] || :v1
+    docs_path = args[:docs_path] || "api/#{version}/docs"
+
+    `yarn run redoc-cli bundle -o public/#{docs_path}/index.html spec/docs/#{version}/apispec.json`
+  end
+
+  task :open, [:version, :docs_path, :host] => :html do |_, args|
+    version = args[:version] || :v1
+    docs_path = args[:docs_path] || "api/#{version}/docs"
+
+    `open public/#{docs_path}/index.html`
   end
 end
 ```
 
 #### 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).
+You can render the HTML yourself with ReDoc:
 
+- [Redoc](https://github.com/Redocly/redoc)
 
 ### Common issues
 
@@ -302,39 +321,6 @@ You might experience some strange issues when generating the documentation. Here
 There seems to be a problem with **rspec-rails** versions 3.7 and later not automatically requiring the project's rails_helper.rb when run with the `--format` flag.
 
 To fix this issue, generate your documentation with `--require rails_helper`:
-
-```
-bundle exec rspec -f Dox::Formatter --order defined --tag dox --out docs.md --require rails_helper
-```
-
-#### 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
-# 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.
@@ -354,4 +340,3 @@ Dox is maintained and sponsored by [Infinum](https://infinum.co).
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-