infinum / dox Goto Github PK

Automated API documentation from Rspec

License: MIT License

Ruby 99.82% Shell 0.18%

ruby open-source

dox's Issues

add base64 data breaks the json format of payload

The JSON format of input data in the generated redoc file shown as one line string includes all request data after adding base64 data as the value of one of the params.

Multipart/form-data support

I run into an issue with generating documentation for next test case:

describe 'Success' do
  let(:headers) { { Authorization: 'auth token' } }
  let(:params) { { image: fixture_file_upload('files/image.jpeg', 'image/jpg') } }

  before do
    put '/api/v1/company/logo', params: params, headers: headers
  end

  it 'renders with updated image' do
    expect(response).to be_ok
    expect(response).to match_json_schema('image/update')
  end
end

My config in rails_helper.rb:

require 'dox'

...

Dox.configure do |config|
  config.header_file_path = Rails.root.join('spec', 'api_doc', 'v1', 'descriptions', 'header.md')
  config.desc_folder_path = Rails.root.join('spec', 'api_doc', 'v1', 'descriptions')
  config.headers_whitelist = ['Accept', 'X-Refresh-Token']
end

config.after(:each, :dox) do |example|
  example.metadata[:request] = request
  example.metadata[:response] = response
end

The error trace:

Traceback (most recent call last):
         6: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/action_printer.rb:9:in `print'
         5: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/action_printer.rb:9:in `each'
         4: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/action_printer.rb:10:in `block in print'
         3: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/example_printer.rb:8:in `print'
         2: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/example_printer.rb:21:in `print_example_request'
         1: from /Users/user/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/example_printer.rb:21:in `puts'
/Users/alexandr/.rbenv/versions/2.6.0/lib/ruby/gems/2.6.0/gems/dox-1.1.0/lib/dox/printers/example_printer.rb:21:in `write': "\xFF" from ASCII-8BIT to UTF-8 (Encoding::UndefinedConversionError)

As it can be seen while debugging it stumbles upon raw image data in request's body.

Add executable for generating html

To avoid using shell scripts to generate html documentation.

[2.0] resource endpoint is not being used anywhere

See if we should put it somewhere or just ignore it
The documentation is pulling it from sample

Is this project still active?

Curious if this is still an active project that just hasn't needed anything, or if it's gone dormant? Doing a survey of options to document my Rails API, and key is if the project is healthy or not.

Add attributes section

https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#attributes-section

This is useful for post requests where you specify what attributes are valid, needed and their types

Request body params duplicates in request query params

When documenting POST, PUT, or PATCH requests in rails 4 applications, the generated documentation includes the request body parameters into the url.

Difficul't use of helpers

because of instance_eval i need to extend helpers module in each action

example:

    document :index do
      action 'Order Index' do
        extend ApiDoc::Shared
        params index_params
        path "/api/{version}/orders{?#{param_keys(index_params)}}"
      end
    end

maybe introduce something like https://github.com/ruby-grape/grape/blob/master/lib/grape/dsl/helpers.rb

Question: is there any way to skip resource definition?

Is it possible to render actions inside of a group to skip the unnecessary level of nesting?

Currently, I have redundant nesting:

Attributes Section and Nested Attributes support

Hello

Api Blueprint has Request Attributes Section:
https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-attributes-section

Also, Apiary supports MSON in request attributes description:
https://help.apiary.io/tools/interactive-documentation/

Added support of these features in my fork of dox-project:
veejar@d0f7127

Error when content-type and accept headers are not application/json

When content-type and accept headers on request are not application/json, e.g. they're set to application/vnd.api+json I get a JSON::ParserError: 784: unexpected token when trying to generate documentation.

When response returns application/vnd.api+json in the headers, documentation can be generated.

Update CHANGELOG.md template

Please use the latest version of Infinum's default changelog template and rename it to CHANGELOG.md:

Changelog

v1.0.0 (YYYY-MM-DD)

Full Changelog

Enhancements

Added something #52

Bugfixes

Fixed something #52

Breaking changes / Deprecations

Changed something #52

Project Dead?

Is this no longer being developed?

Validate action verb attribute

Only valid HTTP verbs should be permitted.

Support for capturing request body

Some of our POST endpoints have a JSON body and I would like to include that in our documentation.

It seems that for the request, just the header information is grabbed. Is there support for request bodies? Could it be added?

OpenAPI bug - description in action block

There seems to be a bug on feature/openapi branch — descriptions added to action block are never rendered.

Steps to reproduce:

Add action block with desc

document :create do
  action 'Create smth' do
    desc 'hello'
  end
end

Generate documentation

The action will be rendered in the generated documentation, but the description is missing. I've tried to pass both inline descriptions and markdown files, but none of them were rendered.

I think the bug is in lib/dox/printers/action_printer.rb file — https://github.com/infinum/dox/pull/46/files#diff-87105a834429cb75e9b69541c6dc3d68. There used to be code there which handled rendering descriptions, but it was removed.

Why Dox supports only JSON-type parameters in request?

Hello

I have question related to parsing API Request Body.
https://github.com/infinum/dox/blob/master/lib/dox/entities/example.rb#L72
Why only JSON-type request is valid? My API allows RAW or JSON type parameters in requests to API. In tests I've used RAW-type and now I should to change a lot of code to use Dox.
Do you plan to add RAW-body support dependent on Content-Type header in request?

Uninitialized constant Dox::Formatter::Forwardable

When I run rspec -f Dox::Formatter I get:

Traceback (most recent call last):
        17: from /usr/local/bundle/bin/rspec:23:in `<main>'
        16: from /usr/local/bundle/bin/rspec:23:in `load'
        15: from /usr/local/bundle/gems/rspec-core-3.7.1/exe/rspec:4:in `<top (required)>'
        14: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:45:in `invoke'
        13: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:71:in `run'
        12: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:86:in `run'
        11: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:99:in `setup'
        10: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:23:in `configure'
         9: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `load_formatters_into'
         8: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `each'
         7: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `block in load_formatters_into'
         6: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration.rb:878:in `add_formatter'
         5: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:146:in `add'
         4: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:177:in `find_formatter'
         3: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:225:in `custom_formatter'
         2: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:225:in `inject'
         1: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:225:in `each'
/usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:225:in `block in custom_formatter': uninitialized constant Dox (NameError)
        17: from /usr/local/bundle/bin/rspec:23:in `<main>'
        16: from /usr/local/bundle/bin/rspec:23:in `load'
        15: from /usr/local/bundle/gems/rspec-core-3.7.1/exe/rspec:4:in `<top (required)>'
        14: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:45:in `invoke'
        13: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:71:in `run'
        12: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:86:in `run'
        11: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:99:in `setup'
        10: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:23:in `configure'
         9: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `load_formatters_into'
         8: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `each'
         7: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `block in load_formatters_into'
         6: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration.rb:878:in `add_formatter'
         5: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:146:in `add'
         4: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:177:in `find_formatter'
         3: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:224:in `custom_formatter'
         2: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:227:in `rescue in custom_formatter'
         1: from /usr/local/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:54:in `require'
/usr/local/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:54:in `require': cannot load such file -- dox/formatter (LoadError)
        21: from /usr/local/bundle/bin/rspec:23:in `<main>'
        20: from /usr/local/bundle/bin/rspec:23:in `load'
        19: from /usr/local/bundle/gems/rspec-core-3.7.1/exe/rspec:4:in `<top (required)>'
        18: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:45:in `invoke'
        17: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:71:in `run'
        16: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:86:in `run'
        15: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/runner.rb:99:in `setup'
        14: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:23:in `configure'
        13: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `load_formatters_into'
        12: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `each'
        11: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration_options.rb:117:in `block in load_formatters_into'
        10: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/configuration.rb:878:in `add_formatter'
         9: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:146:in `add'
         8: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:177:in `find_formatter'
         7: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:224:in `custom_formatter'
         6: from /usr/local/bundle/gems/rspec-core-3.7.1/lib/rspec/core/formatters.rb:227:in `rescue in custom_formatter'
         5: from /usr/local/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:34:in `require'
         4: from /usr/local/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:130:in `rescue in require'
         3: from /usr/local/lib/ruby/2.6.0/rubygems/core_ext/kernel_require.rb:130:in `require'
         2: from /usr/local/bundle/gems/dox-1.1.0/lib/dox/formatter.rb:5:in `<top (required)>'
         1: from /usr/local/bundle/gems/dox-1.1.0/lib/dox/formatter.rb:6:in `<module:Dox>'
/usr/local/bundle/gems/dox-1.1.0/lib/dox/formatter.rb:7:in `<class:Formatter>': uninitialized constant Dox::Formatter::Forwardable (NameError)

I have this in rails_helper.rb:

RSpec.configure do |config|
  config.include FeatureMacros

  config.infer_spec_type_from_file_location!
  config.filter_rails_from_backtrace!

  config.after(:each, :dox) do |example|
    example.metadata[:request] = request
    example.metadata[:response] = response
  end
end

Dox.configure do |config|
  config.header_file_path = Rails.root.join('spec/docs/v2/descriptions/header.md')
  config.desc_folder_path = Rails.root.join('spec/docs/v2/descriptions')
  config.headers_whitelist = %w[Email Password Password-Confirmation
                                Ahoy-Visit Ahoy-Visitor Access-Token
                                Token-Type Client Expiry UID Profile-ID
                                Birth-date Reg-Number Document]
end

Editing the gem folder and adding require 'forwardable' in lib/dox/formatter.rb seems to solve the problem.

headers_whitelist does not seem to be working

Hello, I'm using rails 5.2.2 with dox 1.1.0, I'm using request specs to generate documentation.
The headers included in the documentation are only 'Accept' and 'Content-Type'.

I added this to an initializer.

Dox.configure do |config|
  config.headers_whitelist = ['access-token', 'token-type', 'client', 'expiry', 'uid']
end

But this is not working, when I try and debug it and check the contents of full_headers_whitelist only shows 'Accept' and 'Content-Type'.
Am I missing something here?

Thanks

Undefined method resource_groups inside document block

When I try to use the resource_group method inside the document block I get a

NoMethodError: undefined method 'resource_group' for #<Dox::DSL::Documentation:0x007fafb218fe20>

e.g inside

document :api do
  resource 'Foo' do
    endpoint '/foo'
    group 'Foo'
  end

  resource_group 'bar' do
  end
end

Add dox to api blueprint list

https://github.com/apiaryio/apiblueprint.org/blob/master/data/tools.yaml

Dox::Entities::Action - ArgumentError: wrong number of arguments (0 for 1)

Hitting an exception on this line:

@verb = details[:action_verb] || request.method

https://github.com/infinum/dox/blob/master/lib/dox/entities/action.rb#L11

In my app, request is a Proc and Proc#method expects a symbol as an argument: https://ruby-doc.org/core-2.2.0/Object.html#method-i-method

Some context:

# ./spec/requests/groups/show_spec.rb
describe %(get '/api/groups/:id'), type: :request do
  include Docs::Groups::Api
  let!(:path) { %(/api/groups/#{group.id}) }
  let!(:user) { create(:user_with_groups) }
  let!(:group) { user.groups.last }
  
  context 'when a user is signed in' do
    before { sign_in user }
    before { get path }
    after { sign_out user }

    it 'returns http success (2xx)', :dox do
      include Docs::Groups::Show
      expect(response).to have_http_status(:success)
    end
  end

end

# ./spec/docs/groups.rb
module Docs
  module Groups
    extend Dox::DSL::Syntax

    # define common resource data for each action
    document :api do
      resource 'Groups' do
        endpoint '/groups'
        group 'Groups'
      end
    end

    # define data for specific action
    document :index do
      action 'Get groups'
    end

    document :show do
      action 'Get a group'
    end

  end
end

Can not override action params to be empty

There are only internal params for an action that we use as route default params, but do not want to show in documentation.
I would expect that using

params({})

within an action should remove all the params, but it shows the default ones (that are passed within example request) instead.
Is this expected for some reason on needs a fix?

The current ugly workaround for me is

params(Struct.new(:presence).new({}))

as the gem is using presence internally.

Using tags other than :dox

Hi folks,

This is a fantastic gem!

I have a question on tagging specs to be used in documentation generation. Currently, I have it working as you mention in the readme, tagging specs with :dox and then running the output through the Dox::Formatter.

I was wondering if we could use another tag? The reason for this is I would like to figure out how to seperate public API documentation from private, perhaps by tagging specs as public_dox and private_dox. I tried changing my tags in the specs to private_dox and then reconfiguring the rails_helper.rb configuration as below, but I cannot seem to get the documentation to generate.

  config.after(:each, :private_dox) do |example|
    example.metadata[:request] = request
    example.metadata[:response] = response
  end

Does this use of different tags sound possible? And if so, any idea on what I might be missing to get this different tag working?

Also, this is how I am running the specs to produce the documentation:

bundle exec rspec spec/controllers/api/auth_controller_spec.rb -f Dox::Formatter --order defined --tag private_dox --out docs.md

Header parameters are not generated according to openapi spec

Thank you for this amazing gem!

The schema option need to be added for header parameters. According to open api 3.0.0, parameters should have a schema property.

...
paths:
  /post:
    post:
      parameters:
        - in: header
          name: X-username
          schema:
            type: string
            example: user12345

Currently headers don't have schema property.

paths:
  /post:
    post:
      parameters:
        - in: header
          name: X-username
          example: user12345

Can you please address this issue ?

Content-Type header in request sample section is different than the actual request Content-Type header

The Content-Type header in request sample section does not match actual content type in the request:

The cause of this issue is in the

dox/lib/dox/printers/example_request_printer.rb

Line 50 in 9734fdf

headers.find { |key, _| key == 'Accept' }&.last || 'any'

because it reads Accept header instead of Content-Type header.

When the line is changed to this:

headers.find { |key, _| key == 'Content-Type' }&.last || 'any'

then the out looks correct:

Remove squiggly herecods from tests

Use regular heredocs for multiline strings. Also use heredocs in printers.

I think headers_whitelist does not work

When i add ['Accpet'] to headers_whitelist this is what i get:

    + Headers

            Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
            Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
            Content-Type: application/x-www-form-urlencoded

grape api and request specs

Possible to filter response values?

How is the response picked up within rspec?

I would like to replace some response values with something generic.

Feature Request: Support Open API Extensions for branding purposes

Thanks for this great library! 🙏

Open API Extensions are supported by some doc generators like Redoc and allow us to add branding, e.g. x-logo. It would be great if we can add this in the Dox configuration, perhaps namespaced under extensions or similar, for example:

Dox.configure do |config|
  # ...

  config.extensions['x-logo'] = {
    "url": "https://example.com/logo.png",
    "backgroundColor": "#ff3399"
  }

  # ...
end

I was able to add support for automated branding afterwards with the following script:

#!/usr/local/bin/ruby
require 'json'

docs = File.read('spec/api_doc/v1/schemas/docs.json')
docs_json = JSON.parse(docs)

docs_json['info']['x-logo'] = {
  "url": "https://example.com/logo.png",
  "backgroundColor": "#ff3399"
}

updated_docs = JSON.pretty_generate(docs_json)

File.write('spec/api_doc/v1/schemas/docs.json', updated_docs)

Script reference

Thanks again for all your great work on this library.

This should be dropped in the new version and tests that should be documented should be whitelisted with :doc or similar option.

Create an example app

Example app with different usage combinations.